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-#2#2-Stretch.TEXT 
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BEGIN { main program } 

{ Initialization - Generic to all applications usii\g QuickDraw 

QDInit[@heapBuf, @heapBiii[8192], (o^heapErroi); 

OpenPort(@myPort) ; 

PaintRecttthePort" .portRect] ; 

Initlcons; {moved to here from below stuffhex} 

InitScales; {moved, to here from Taelow stuffhex} 

DrawStuff; 

REPEAT UNTIL KeyBdEventCFALSE, FALSE, event) AND 

(event.ascii o CHR[1]); 



PaintRect(thePort" .portRect); 
SetRect[srcRect, 0, 0, 720, 360) ; 
myPicture := OpenPictureCsrcRect); 
DrawStuff; 



n 



-#2#2-Hemisphere.TEXT 



PROCEDURE DrwFigure(vietfftng, rollRng, pi 
BEGIN 

Vietfflngl4(vie«ftng); 

Identity; 

Roll(rollflng); 

Pitch(fiitchflng); 

EraseRectCportr .portRect); 

Fran eRectCportf .portRect); 

PlotGrid; 



tchflng 



^ 
fl 
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Preface 



This manual Is Intended for Pascal programmers. It describes an implemen- 
tation of Pascal for the Lisa computer. The compiler and code generator 
translate Pascal source text to MC68000 object code. 

The language is reasonably compatible with Apple II and Apple III Pascal. See 
Appendix A for a discussion of the differences between these forms of Pascal. 

In addition to providing nearly all the features of standard Pascal^ as described 
in the Pascal User Manual and Refxjrt (Jensen and Wirth), this Pascal provides 
a variety of extensions. These are summarized In Appendix A. They include 
32-bit integers^ an otherwise clause In case statements^ procedural and 
functional parameters with type-checked parameter llsts^ and the • operator 
for obtaining a pointer to an object. The real arithmetic conforms to many 
aspects of the proposed IEEE standard for single-precision arithmetic. 

Operating Environment 

The compiler will operate In any standard Lisa hardware configuration; this 
manual assumes the Workshop software environment. 

Related Documents 

Pascal User Manual ancf Report, Jensen and Wlrth, Sprlnger-Verlag 1975. 

Workshop User's Guide for the Lisa, Apple Computer, Inc. 1983. 
other Lisa documentation. 

Definitions 

For the purposes of this manual the following definitions are used: 

• Error: Either a run-time error or a compiler error. 

• Scope: The body of text for which the declaration of an Identifier or 
l^el Is valid. 

• Undefined: The value of a variable or function when the variable does not 
necessarily have a meaningful value of Its type assigned to It 

• Unspecified: A value or action or effect that, although possibly 
well-defined. Is not specified and may not be the same In all cases or for 
all versions or configurations of the system. Any programming construct 
that leads to an unspecified result or effect Is not supported. 

Notation and Syntax Diagrams 

All numbers in this manual are in decimal notation, except where hexadecimal 
notation Is specifically indicated. 

Throughout this manual, bold-face type Is used to distinguish Pascal text from 
English text. For example, sqi(n div 16) represents a fragment of a Pascal 
program. Sometimes the same word appears both in plain text and In 
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bold-face; for example, "The declaration of a Pascal procedure Deglns with 
the word procedure." 

Italics are used when technical terms are introduced. 

Pascal syntax is specified by diagrams. For example, the following diagram 
gives the syntax for an identifier: 



identjfjer 


^ 


letter 












^ 












]4 ' 












letter 














digit 


^ > 






^ 
















V 


underscore 


^ 





Start at the left and follow the arrows through the diagram. Numerous paths 
are possible. Every path that begins at the left and ends at the arrow-head on 
the right is valid, and represents a valid way to construct an identifier. The 
boxes traversed by a path through the diagram represent the elements that can 
be used to construct an identifier. Thus the diagram embodies the following 
rules: 

• An identifier must begin with a letter, since the first arrow goes directly to 
a box containing the name "letter." 

• An identifier might consist of nothing but a single letter, since there is a 
path from this box to the arrow-head on the right, without going through 
any more boxes. 

• The initial letter may be followed by another letter, a digit, or an 
uncferscore, since there are branches of the path that lead to these boxes. 

• The initial letter may be followed by any number of letters, digits, or 
underscores, since there is a loop in the path. 

A word contained in a rectangular box may be a name for an atomic element 
like "letter" or "digit," or it may be a name for some other syntactic 
construction that is specified \3y another diagram. The name in a rectangular 
box is to be replaced by an actual instance of the atom or construction that it 
represents, e.g. "5* for "digit" or "countei" for "variable-reference". 

Pascal symbols, such as reserved words, operators, and punctuation, are 
bold-face and are enclosed in circles or ovals, as in the following diagram for 
the construction of a compound-statement: 



compound-statement 



■ ^ begin) - 



I 



statement 



T 



>{«Td)- 



Pascal Reference ManuaJ Preface 



Text in a circle or oval represents itself, and is to be written as snown (except 
that capitalization of letters is not significant). In trie diagram above, the 
semicolon and the words begin and end are symbols. The word "statement" 
refers to a construction that has its own syntax diagram. 

A compound-statement consists of the reserved word begin, followed by any 
number of statements separated by semicolons, followed by the reserved word 
ena (As will be seen in Chapter 6, a statement may be null; thus begin end is 
a valid compound-statement) 
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Tokens and Constants 



Tokens are the smallest meaningful units of text In a Pascal program; 
structurally^ tney correspond to the words In an English sentence. The tokens 
of Pascal are classified into specJal symbols, identifJen, numben, labels, and 

quoted string constants 

The text of a Pascal program consists of tokens and separators;^ separator is 
either a blank or a comment Two adjacent tokens must be separated by one 
or more separators, if both tokens are identifiers, numben, or reserved words. 

No separators can be embedded within tokens, except in quoted string 
constants. 

1.1 Character Set and Special Symbols 

The Character set used by Pascal on the Lisa is 8-blt extended ASCII, with 
Characters represented by numeric codes in the range from to 255. 

Letters, digits, hex-digits, and blanks are subsets of the character set: 

• The letters are those of the English alphabet, A through z and a through z. 

• The digits are the Arabic numerals through 9; the hex-digits are the 
Arabic numerals through 9, the letters A through F, and the letters a 
through f. 

• The blanks are the space character (ASCII 32), the horizontal tab character 
(ASCII 9), and the CR character (ASCII 13). 

Special symbols and reserved words are tokens having one or more fixed 
meanings. The following single characters are special symbols: 



The following character pairs are special symbols: 
<><=>= := .. (* *) 

The following are the reserved words: 



{ }$ 



and 


end 


label 


progiam 


until 


array 


file 


methods* 


record 


uses 


begin 


for 


mod 


repeat 


var 


case 


function 


nil 


set 


While 


const 


goto 


not 


string 


with 


creation* 


if 


of 


subclass* 




div 


implementation 


or 


then 




downto 


in 


otherwise 


to 




do 


interface 


packed 


type 




else 


intrinsic* 


piDcedure 


unit 
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The reserved words marked with asterisks are reserved for future use. 
Corresponding upper and lower case letters are equivalent In reserved words. 
Only the first 8 characters of a reserved word are significant. 

1.2 Identifiers 

Identifiers serve to denote constants, types, variables, procedures, functions, 
units and programs, and fields In records. Identifiers can be of any length, but 
only the first 8 characters are significant. Corresponding upper and lower case 
letters are equivalent in identifiers. 



Jdentjfier 



♦■ letter 



"^ 





letter 


^ J 








digit 


^ J 


* 








\ 


underscore 


^ 



NOTE 



The first 8 characters of an Identifier must not match the first 8 char- 
acters of a reserved word. 



Ex&jpies Of laentJflers: 



Rome 



They 



gcd SUM getjDyte 

13 Directives 

Directives are words that have special meanings In particular contexts, 
are not reserved and can be used as identifiers in other contexts. For 
example, the word forward Is Interpreted as a directive if it occurs 
immediately after a procedure-heading or function-heading, but in any other 
position it Is Interpreted as an identifier. 

1.4 Numbers 

The usual decimal notation is used for numbers that are constants of the data 
types integer, longint, and real (see Section 3.1.1). Also, a hexadecimal integer 
constant uses the $ character as a prefix (1-4 digits for integer, 5-8 digits for 
longintX 



aiQii-semJence ^ ^,„,. ^ 


j^ 9' ulylL -s ^ 


^- ) 



hex-diglt-s&^^jeniie 



Z 



hex-digit 



J 
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unsianecZ-inteaer 




digit-sequence 



hex-diglt-sequence 



r^ 



sign 



G> 




unsigned-real 



— H^^g^^"^^^"^*^^ "^vK-y^ digit-sequence -^ — / 

^^ ^ scale-factor -^ 



scale-factor 



■d) 




sign 



digit-sequence 



unsigned-number 



T2 



unsigned-integer 



unsigned-real 



signed-numtjer 



Vr— t/ 
^* sian -^ 



sign 



unsigned-number 



The letter E or e preceding the scale in an unsigned-real means "times ten to 
the power of". 

Examples of numbers: 

1 +100 -0.1 5E-3 87.35e+8 $A050 

Note that 5E-3 means 5x10"^, and 87.35e+8 means 87.35x10^. 
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1.5 Labels 

A label is a digit-sequence in the range from through 9999. 

1.6 Quoted String Constants 

A quoted-string-constant is a sequence of zero or more characters^ all on one 
line of the program source text and enclosed Dy apostrophes. Currently^ the 
maximum number of characters is 255. A quoted-string-constant with nothing 
between the apostrophes denotes the null string. 

If the quoted-string-constant is to contain an apostrophe, this apostrophe must 
be written twice. 



quoted-string-constant 

—►TV 



^ 



string-character 



^ 



O. 



string-cnaracter 



■^ 



any char except (jj /arCR 



T 



•O-O 



Exa/rpJes of quoteo-string-constants: 
•pascal* 'THIS IS A STRING' 



■Don*'t worry! 



All String values have a length attribute (see Section 3.1.1.6). In the case of a 
string constant value the length is fixed; it is equal to the actual number of 
characters in the string value. 

1.6.1 Quoted Character Constants 

Syntactically, a quoted-character-constant is simply a quoted-string-constant 
whose length is exactly 1. 



g/otecf-character-constant 



^Qj — ► ! string-character — ^\_) — ^ 



A quoted-character-constant is compatible with any char-type or string-type; 
that is, it can be used either as a character value or as a string value. 
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1.7 Constant Declarations 

A constant-declaration defines an identifier to denote a constant, within the 
block that contains the declaration. The scope of a constant-identifier (see 
Chapter 2) does not include its own declaration. 



constant-declaration 



identifier — ^^^ — » constant — ^T) — ► 



constant 



"\ 



WsimV 



constant-identifier 



""^ slgned-number 



^^ quoted-string 



^ quoted-char 



^ 



i.^ 



NOTE 



A constant-identifier is an identifier that has already been declared to 
denote a constant. 



A constant-identifier following a sign must denote a value of type Integer, 
longint, or real. 

1.8 comments and compiler commands 

The constructs: 

I any text not containing right-brace } 

(» any text not containing star-right-paren *) 

are called cmvn&its 

A compiler command is a comment that contains a $ character immediately 
after the { or (* that begins the comment. The $ character is followed by the 
mnemonic of the compiler command (see Chapter 12). 

Apart from the effects of compiler commands, the substitution of a blank for a 
comment does not alter the meaning of a program. 

A comment cannot be nested within another comment formed with the same 
kind of delimiters. However, a comment formed with {...} delimiters can be 
nested within a comment formed with (*...») delimiters, and vice versa. 
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2.1 Definition of a Block 

A block consists of declarations and a statement-part. Every block is part of 
a procedure-declaration^ a function-declaration^ a program, or a unit. All 
identifiers and labels that are declared in a particular block are local to that 
block. 



block 






"•^ constant-declaration-part 



label-declaration-part 



D 



r 



n 



type-declaratim-part 



LD 



^ variable-declaration-part 



r 



n 



procedure-and-function-declaration-part 



^ 



D 



M^ statement-part 



The label-cfeclaratlon-partdi&claxBZ all labels that mark statements in the 
corresponding statement-part. Each label must mark exactly one statement in 
the statement-part. 



labehdeclaraUon-pait 

<^) 



C 



label 




<i> 



label 



^ digit-sequence 
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The const&it-cfeclaraUm-partCiQT\\J3^w% all constant-declarations local to the 
block. 

cxKistant-declaraUon-part 



►( ^const^ 



r 



constant-declaration 



1 



The type-c/eclaratj'on-partcQV\\.dSn% all type-declarations local to the block. 

t)^-c^laraUon-part 
M^^> 



I 



type-declaration 



The uanadle-cfeclaraUon-partoonXjaXm all variable-declarations local to the 
block. 



varidble-cleclaraUai-part 







i^ ; 



The proceaure-ancl~funcUon-cleclaration-parton^\v& all procedure and 
function declarations local to the block. 

pnx:eckjre-&xl-fux;Ucxi-cleclaraUai-part 
T 



^ 



procedure-declaration 



function-declaration 



The ^^^^y73ey?/-/:ar/ specifies the algorithmic actions to be executed upon an 
activation of the block. 



statement-part 



^ compound-statement 
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At run time, all variables declared within a particular block have 
unspecified values each time the statement-part of the block is entered. 

2.2 Rules of Scope 

This chapter discusses the scope of objects wJthln the program or unit In wnicn 
tney are defined See Chapter 9 for the scope of objects defined in the 
interface-part of a unit and referenced in a host program or unit. 

2.2.1 Scope of a Declaration 

The appearance of an identifier or label in a declaration defines the identifier 
or label. All corresponding occurrences of the identifier or label must be 
within the scope of this declaration. 

This scope is the block that contains the declaration, and all blocks enclosed 
by that block except as explained in Section 2.2.2 below. 

2.2.2 Redeclaration in an Enclosed Block 

Suppose that outer is a block, and inner is another block that is enclosed 
within outer. If an identifier declared in block outer has a further declaration 
in block inner, then block inner and all blocks enclosed by inner are excluded 
from the scope of the declaration in block outer. (See Appendix B for some 
odd cases.) 

2.2.3 Position of Declaration within Its Block 

The declaration of an identifier or label must precede all corresponding 
occurrences of that identifier or label in the program text— i.e., identifiers and 
labels cannot be used until after they are declared. 

There is one exception to this rule: The base-type of a pointer-type (see 
Section 3.3) can be an identifier that has not yet been declared. In this case, 
the identifier must be declared somewhere in the same type-declaration-part 
in which the pointer-type occurs. (See Appendix B for some odd cases.) 

2.2.4 Redeclaration within a Block 

An identifier or label cannot be declared more than once in the outer level of 
a particular block, except for record field identifiers. 

A record field identifier (see Sections 3.2.2, 4.3, and 4.3.2) is declared within a 
record-type. It is meaningful only in combination with a reference to a 
variable of that record-type. Therefore a field identifier can be declared 
again within the same block, as long as it is not declared again at the same 
level within the same record-type. Also, an identifier that has been declared 
to denote a constant, a type, or a variable can be declared again as a record 
field identifier in the same block. 
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223 Identifiers of Standard Objects 

Pascal on the Lisa provides a set of standard (predeclared) constants^ types, 
procedures, and functions. The Identifiers of these objects behave as if they 
were declared in an outermost block enclosing the entire program; thus their 
scope includes the entire program. 
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Data Types 



A type is used in declaring variables; it determines the set of values which 
those variables can assume, and the operations that can be performed upon 
them. A type-cfec]araUon associates an identifier with a type. 



tyve-decJamtJon 



identifier 



O 



type 



•Q> 



type 



simple-type 



^^ 



structured-type 



pointer-type 



The occurrence of an identifier on the left-hand side of a type-declaration 
declares it as a type-identifier for the block in which the type-declaration 
occurs. The scope of a type-identifier does not include its own declaration, 
except for pointer-types (see sections 2.2.3 and 3.3). 

To help clarify the syntax description with some semantic hints, the following 
terms are used to distinguish identifiers according to what they denote. 
Syntactically, all of them mean simply an identifier: 

simple-type-identifier 

structured-type-identifier 

pointer-type-identifier 

ordinal-type-ldentifler 

real-type-identifier 

string-type-ldentifler 

In other words, a simple-type-identifier is any identifier that is declared to 
denote a simple type, a structured-type-identifier is any identifier that is 
declared to denote a structured type, and so forth. A simple-type-identifier 
can be the predeclared identifier of a standard type such as integer, boolean, 
etc. 
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3.1 Simple-Types (and Ordinal-Types) 

All the simple-types define ordered sets of values. 



simple-type 



ordinal-type 



^— ^ real-type 



> string-type 



^ 



real-type ^ i - real-type-identifier 



ordinal-type 



subrange-type 



enumerated- type 



ordinal-type-identlfler 



The standard real-type-identifier is real. 

String-types are discussed in Section 3.1.1.6 below. 

(Mlnal-tyf^s are a subset of the simple-types, with the following special 
characteristics: 

• Within a given ordinal-type, the possible values are an ordered set and each 
possible value is associated with an ordlnallty, which is an integer value. 
The first value of the ordinal-type has ordinality 0, the next has ordinality 
1, etc. Each possible value except the first has a predecessor based on 
this ordering, and each possible value except the last has a successor based 
on this ordering. 

• The standard function ord (see Section 11.5.1) can be applied to any value 
of ordinal-type, and returns the ordinality of the value. 

• The standard function pred (see Section 11.5.4) can be applied to any value 
of ordinal-type, and returns the predecessor of the value. (For the first 
value in the ordinal-type, the result is unspecified.) 

• The standard function succ (see Section 11.5.3) can be applied to any value 
of ordinal-type, and returns the successor of the value. (For the first value 
in the ordinal-type, the result is unspecified.) 
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All simple-lypes except real and the string-types are ordinal-types. The 
standard ordinal-type-identifiers are: 

Integer 
longint 
char 
boolean 

Note that in addition to these standard types^ the enumerated-types and 
subrange-types are ordinal-types. 

3.1.1 Standard Simple-Types and String-Types 

A Standard type is denoted by a predefined type-identifier. The slnnple-types 
integer, longint, real, char, and boolean are standard. The string-types are 
user-cfefined simple-types. 

3.L1.1 The Integer Type 

The values are a subset of the whole numbers. (As constants, these values can 
be denoted as specified in Section 1.4.) The predefined integer constant maxint 
is defined to be 32767. Maxint defines the range of the type Integer as the 
set of values: 

-maxint- 1, -maxint, ... -1, 0, 1, ... maxint- 1, maxint 

These are 16-bit, 2*s-complement integers. 

3.1.1.2 The Longint Type 

The values are a subset of the whole numbers. (As constants, these values can 

be denoted as specified in Section 1.4.) The range is the set of values from 

-(2^^-l) to 2^^-l, i.e., -2147483648 to 2147483647. 

These are 32-bit integers. 

Arithmetic on integer and longint operands is done in both 16-bit and 32-bit 
precision. An expression with mixed operand sizes is evaluated in a manner 
similar to the FORTRAN single/double precision floating-point arithmetic rules: 

• All "integer" constants in the range of type integer are considered to be of 
type integer. All "Integer" constants in the range of type longint, but not 
in the range of type integer, are considered to be of type lon^nt 

• When both operands of an operator (or the single operand of a unary 
operator) are of type integer, i6-bit operations are always performed and 
the result is of type integer (truncated to 16 bits if necessary). 

• Vy/hen one or both operands are of type longint, all operands are first 
converted to type longint, 32-bit operations are performed, and the result is 
of type longint However, if this value is assigned to a variable of type 
int^r, it is truncated (see next rule). 
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• The expression on the right of an assignment statement is evaluated 
fnc^xrvienUy of the size of tl^ i/arfaDle m tt^ left If necessary^ the 
result of the expression is truncated or extended to match the size of the 
variable on the left 

The oim function (see Section 11.3.3) can be used to convert an integer value 
to a longint value. 

IMPLEMENTATION NOTE 

There is a performance penalty for the use of longint values. The 
penalty is essentially a factor of 2 for operations other than division 
and multiplication; for division and multiplication, the penalty Is much 
worse than a factor of 2. 



3.1.13 The Real Type 

For details of IEEE standard floating-point arithmetic, see Appendix D. The 
possible real values are 

• Finite values (a subset of the mathematical real numben). As constants, 
these values can be denoted as specified in Section 1.4. 

The largest absolute numeric real value is approximately 3.402823466E38 in 
Pascal notation. 

The smallest absolute numeric non-zero real value is approximately 
1.401298464E-45 in Pascal notation. 

The real zero value has a sign, like other numbers. However, the sign of a 
zero value is disregarded except in division of a finite number by zero and 
in textual output. 

• Infinite values, +« and -». These arise either as the result of an operation 
that overflows the maximum absolute finite value, or as the result of 
dividing a finite value by zero. Appendix D gives the rules for arithmetic 
operations using these values. 

• NaNs (the word "NaN" stands for "Not a Number"). These are values of 
type real that convey diagnostic information. For example, the result of 
multiplying «» by is a NaN. 

3.1.1.4 The Boolean Type 

The values are truth values denoted by the predefined constant identifiers false 
and true. These values are ordered so that false is "less than" true. The 
function-call ord(false) returns 0, and orcl(true) returns 1 (see Section 11.5.1). 

3.1.13 TUB Char Type 

The values are extended 8-bit ASCII, represented by numeric codes in the 
range 0..255. The ordering of the char values is defined by the ordering of 
these numeric codes. The function-call ord(c), where c is a char value, returns 
the numeric code of c (see Section 11.5.1). 
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3.L1.6 String-Types 

A string value is a sequence of cnaracters that has a dynamic length attri- 
bute. The length is the actual number of characters in the sequence at any 
time during program execution. 

A string type has a static size attribute. The size Is the maximum limit on 
the length of any value of this type. The current value of the length attribute 
Is returned by the standard function length (see Section 11.6); the size attribute 
of a string type Is determined when the string type Is defined. 

string-type 



r» ( string 3 — MT) — ► size-attribute — Kj) — T 
» strlng-type-ldentlfler ^ 



size-attrit)ute 



unsigned-Integer 



where the size attribute is an unsigned-integer. 

IMPLEMENTATION NOTE 



In the current Implementation^ the size-attribute must be In the range 
from 1 to 255. 



The ordering relationship between any two string values Is determined by 
lexical comparison based on the ordering relationship between character values 
In corresponding positions In the two strings. (When the two strings are of 
unequal lengths, each character In the longer string that does not correspond to 
a character In the shorter one compares "higher"; thus the string 'attribute' Is 
ordered higher than 'at'.) 

Do not confuse the size with the length. 
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NOTES 

The size attribute of a string constant is equal to the length of the 
string constant value^ namely the number of characters actually in the 
string. 

Although string-types are simple-types by definition, they have some 
characteristics of structured-types. As explained in Section 4.3.1, 
individual characters In a string can be accessed as if they were 
components of an array. Also, all string-types are implicitly packed 
types and all restrictions on packed types apply to strings (see Sections 
7.3.2, 5.1.6.1, and 11.7). 

Do not make any assumptions about the internal storage format of strings, as 
this format may not be the same in all implementations. 

Operators applicable to strings are specified in Section 5.1.5. Standard 
procedures and functions for manipulating strings are described in Section 11.6. 

3.1.2 Enumerated-Types 

An enumerated-type defines an ordered set of values by listing the identifiers 
that denote these values. The ordering of these values is determined by the 
sequence in which the identifiers are listed. 



enameratea-type ^ ( Jy.^ ldentifier^^iiir|--»()>-» 



identifier-list 



identifier 



^ — O-^ 

The occurrence of an identifier within the identifier-list of an 
enumerated-type declares it as a constant for the block in which the 
enumerated-type is declared. The type of this constant is the enumerated-type 
being declared. 

Examples of enumerated-types: 

color = (red, yellow, green, blue) 

suit = (club, diamond, heart, spade) 

roarltaistatus = (married, divorced, widoiped, single) 

Given these declarations, yellow is a constant of type color, diamond is a 
constant of type suit, and so forth. 

When the ord function (see Section 11.5.1) is applied to a value of an 
enumerated-type, it returns an integer representing the ordering of the value 
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wltn respect to the other values of the enumerated-type. For example, given 
the declarations above, ord(red) returns 0, ord(yellow) returns l, and ord(blue) 
returns 3. 

3.1.3 Subrange-Types 

A subrange-type provides for range-checking of values within some 
ordinal-type. The syntax for a subrange-type is 

subrange-type 



Both constants must be of ordinal-type. Both constants must either be of the 
same ordinal-type, or one must be of type integer and the other of type 
longint If both are of the same ordinal-type, this type is called the host-type 
If one is of type integer and the other of type longint, the host-type is longint 
Note that no range-checKing is done if the host-type is longint 

Examples of subrange-types: 

1..100 
-10.. ♦lO 

red.. green 

A variable of subrange-type possesses all the properties of variables of the 
host type, with the restriction that Its run-time value must be In the specified 
closed interval. 

IMPLEMENTATION NOTE 

Range-Checking Is enabled and disabled by the compiler commands $R+ 
and $R- (see Chapter 12). The default is $R+ (range-checking enabled). 



3.2 Structured-Types 

A Structured-type is characterized by its structuring method and by the type(s) 
of its components. If the component type is Itself structured, the resulting 
structured-type exhibits more than one level of structuring. There is no 
specified limit on the number of levels to which data-types can be structured. 
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The use of the word packed in the declaration of a structured-type indicates 
to the compiler that data storage should be economized, even if this causes an 
access to a component of a variable of this type to be less efficient 

The word packed only affects the representation of one level of the 
structured-type in which it occurs. If a component is itself structured, the 
component's representation Is packed only if the word packed also occurs in 
the declaration of its type. 

For restrictions on the use of components of packed variables, see Sections 
7.3.2, 5.1.6.1, and 11.7. 

The implementation of packing is complex, and details of the allocation of 
storage to components of a packed variable are unspecified 

IMPLEMENTATION NOTTE 

In the current implementation, the word packed has no effect on types 
other than array and record. 

3^.1 Array-Types 

An array-type consists of a fixed number of components that are all of one 
type, called the component-typa The number of elements is determined ti'^ 
one or more index-types, one for each dimension of the array. There Is no 
specified limit on the number of dimensions. In each dimension, the array can 
be Indexed by every possible value of the corresponding Index-type, so the 
number of elements is the product of the cardinalities of all the Index-types. 

array-type 

-» (arrayy -»(TVr-» rindex-type h yKT^-KoT)' ^ ^VP^I ^ 



o 



T 



index-type 



ordinal-type 



The type following the word of Is the component-type of the array. 

IMPLEMENTATION NOTE 

In the current implementation, the Index-type should not be longint or a 
subrange of longint, and arrays should not contain more than 32767 bytes. 
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Examples of array- types: 

array [1.. 100] of real 
array [boolean] of color 

If the component-type of an array-type is also an array-type^ the result can be 
regarded as a single multi-dimensional array. The declaration of such an array 
is equivalent to the declaration of a multi-dimensional array, as illustrated by 
the following examples: 

array[boolean] of array[1..10] of array[size] of real 
is equivalent to: 

array [boolean, 1.. 10, size] of real 
Likewise, 

packed array[l..lO] of packed array[l..8] of boolean 
is equivalent to: 

packed array[1..10,l..8] of boolean 

"Equivalent" means that the compiler does the same thing with the two 
constructions. 

A component of an array can be accessed by referencing the array and 
applying one or more indexes (see Section 4.3.1). 

3.2.2 Record-Types 

A record-type consists of a fixed number of components called fields, possibly 
of different types. For each component, the record-type declaration specifies 
the type of the field and an identifier that denotes it. 



record-type ^ Q ^^^^ 
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flelcf-aeclaraUon 



The fixed-part of a record-type specifies a list of "fixed" fields, giving an 
identifier and a type for each field. Each of these fields contains data that is 
always accessed in the same way (see Section 4.3.2). 

Example of a record-type: 

record 

year: integer; 

month: 1..12; 

day: 1..31 
end 

A variant-part allocates memory space with more than one list of fields, thus 
permitting the data in this space to be accessed in more than one way. Each 
list of fields is called a variant The variants "overlay" each other in memory, 
and all fields of all variants are accessible at all times. 



variant-part 
>case 



^ identifie r"l-»(Ty 



tag-field-type -^2^ 



r 



variant 
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<T>-^ 



taq-field-ti^xf 



ordinal-type-ldentifier 



IMPLEMENTATION NOTE 



In the current Implementation, the type longint should not be used as a 
tag-type as it will not work correctly. 
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Each variant is introduced by one or more constants. All the constants must 
be distinct and must be of an ordinal-type that is compatible with the 
tag-type (see Section 3.4). 

The variant-part allows for an optional identifier, called the tag-fleia 
iaentlfler. If a tag-field identifier is present, it is automatically declared as 
the identifier of an additional fixed field of the record, called the tag-field 

The value of the tag-field may be used by the program to indicate which 
variant should be used at a given time. If there is no tag-field, then the 
program must select a variant on some other criterioa 

Examples of record-types with variants: 

record 
name, fIrstName: string[80]; 
age: 0..99; 

case married: boolean of 
true: (spousesName: strlng[80]); 
false: () 
end 

record 
>oy: real; 
area: real; 
case s: sT^pe of 
triangle: (side: real; inclination, anglel, angleZ: 

angler- 
rectangle: (sidel, side2 : real; skew, angle3: angle); 
circle: (diameter: real); 
end 

NOTE 

The constants that introduce a variant are not used for referring to 
fields of the variant; however, they can be used as optional arguments 
of the new procedure (see Section 11.2). Variant fields are accessed in 
exactly the same way as fixed fields (see Section 4.3.2). 

3.2.3 Set-Types 

A set-type defines a range of values that is the powerset of some ordinal-type, 
called the base-type In other words, each possible value of a set-type is some 
subset of the possible values of the base-type. 



set-type — »(^^P)-»QP)-> j ordinal-type 
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IMPLEMENTATION NOTE 

In the present implementation the base-type must not be longint The 
base-type must not have more than 4088 possible values. If the base- 
type is a subrange of integer, it must be within the limits 0..4087. 

Operators applicable to sets are specified in Section 5.1.4. Section 5.3 shows 
how set values are denoted in Pascal. 

Sets with less than 32 possible values in the base-type can be held in a 
register and offer the best performance. For sets larger than this, there is a 
performance penalty that is essentially a linear function of the size of the 
base-type. 

The empty set (see Section 5.1.4) is a possible value of every set-type. 

3.2.4 File-Types 

A file-type is a structured-type consisting of a sequence of components that 
are all of one type, the compoiwnt-typa The component-type may be any 
type. 

The component data is not in program-addressable memory but is accessed via 
a peripheral device. The number of components (i.e. the length of the file) is 
not fixed by the file- type declaration. 



file-type 



<«te> 



W(or)-» | type y 



The type file (without the "of type" construct) represents a so-called "untyped 
file" type for use with the blockread and blockwrlte functions (see Section 

10.4). 

NOTE 

Although the symbol file can be used as if it were a type-identifier, it 
cannot be redeclared since it is a reserved word. 



The standard file-type text denotes a file of text organized into lines. The 
file may be stored on a file-structured device, or it may be a stream of 
characters from a character device such as the Lisa keyboard. Files of type 
text are supported by the specialized I/O procedures discussed in Section 10.3. 

In Pascal on the Lisa, the type text is distinct from the type file of char 
(unlike standard Pascal). The type file of char is a file whose records are of 
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type char, containing char values that are not interpreted or converted in any 
way during I/O operations. 

In a stored file of type text or file of -128..127, the component values are 
packed into bytes on the storage medium. However, this does not apply to the 
type file of char; the component values of this type are stored in 16-bit words. 

In Pascal on the Lisa, files can be passed to procedures and functions as 
variable parameters, as explained in Section 7.3.2. 

Sections 4.3.3, 10.2, 10.3, and 10.4 discuss methods of accessing file components 
and data. 

3.3 Pointer-Types 

A pointer- type defines an unbounded set of values that point to variables of a 
specified type called the txase-t}^ 

Pointer values are created by the standard procedure new (see Section 11.2.1), 
by the » operator (see Section 5.1.6), and by the standard procedure pointer 
(see Section 11.3.4). 



ixjJnter-ti^x 



^ DC 



{/}-#■ base- type 



pointer-type-identifier 



base-type 



type-identifier 



NOTE 



The base-type may be an identifier that has not yet been declared, 
this case, it must be declared somewhere in the same block as the 
pointer-type. 



In 



3.4 



The special symbol nil represents a standard pointer-valued constant that is a 
possible value of every pointer type. Conceptually, nil is a pointer that does 
not point to anything. 

Section 4.3.4 discusses the syntax for referencing the object pointed to by a 
pointer variable. 

Identical and Compatible Types 

As explained below, this Pascal has stronger typing than standard Pascal. In 
Pascal on the Lisa, two types may or may not be identical and identity is 
required in some contexts but not in others. 
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Even if not identical, two types may still be compatible, and this is sufficient 
in contexts where identity is not required—except for assignment, where 
assignment-compatibility is required. 

3A1 Type Identity 

Identical types are required only in the following contexts: 

• Variable parameters (see Section 7.3.2). 

• Result types of functional parameters (see Section 7.3.4). 

• Value and variable parameters within parameter-lists of procedural or 
functional parameters (see Section 7.3.5). 

• One-dimensional packed arrays of char being compared via a relational 
operator (see section 5.1.5). 

Two types, tl and t2, are identical if either of the following is true: 

• The same type icfentifler is used to declare both tl and t2, as in 

foe = "integer; 
tl = foo; 
t2 = f 00; 

• tl is declared to be equivalent to t2 as in 

tl = t2; 

Note that the declarations 

tl = t2; 
t3 = tl; 

do not make t3 and t2 identical, even though they make tl identical to t2 and 
t3 identical to tl! 

Also note that the declarations 

t4 = integer; 
t5 = integer; 

do make t4 and t5 identical, since both are defined by the same type 
identifier. In general, the declarations 

t6 = t7; 
t8 = t7; 

do make t6 and t8 identical if t7 is a type-identifier. 

However, the declarations 

t9 = "integer; 
tlO = "integer; 

do not make t9 and tlO identical since "integer is not a type identifier but a 
user-defined type consisting of the special symbol " and a type identifier. 
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Finally, note that two variables declared in the same declaration, as in 

vari, var2: "integers- 
are of identical type. However, if the declarations are separate then the 
definitions above apply. 

The declarations 

varl: "integer; 

var2: "Integer; 

\/ar3: integer; 

var4: integer; 

make var3 and var4 identical in type, but not varl and var2. 

3.4.2 Compatibility of Types 

Compatibility is required in the majority of contexts where two or more 
entities are used together, e.g. in expressions. Specific instances where type 
compatibility is required are noted elsewhere in this manual. 

Two types are compaUble if any of the following are true: 

• They are identical. 

• One is a subrange of the other. 

• Both are subranges of the same type. 

• Both are string- types (the lengths and sizes may differ). 

• Both are set-types, and their base-types are compatible. 

3.4.3 Assignment-Compatibility 

Assignment-compatibility is required whenever a value is assigned to 
something, either explicitly (as in an assignment-statement) or implicitly (as in 
passing value parameters). 

The value of an expression expval of type exptyp is assignment-compatible 
with a variable, parameter, or function-jdentifier of type vtyp if any of the 
following is true. 

• vtyp and exptyp are identical and neither is a file-type, or a structured- 
type with a file component. \ 

• vtyp is real and exptyp is integer or longint (expval is coerced to type 
real). 

• vtyp and exptyp are compatible ordinal-types, and expval is within the 
range of possible values of vtyp. 

• vtyp and exptyp are compatible set- types, and all the members of expval 
are within the range of possible values of the base- type of vtyp. 

• vtyp and exptyp are string types, and the current length of expval is equal 
to or less than the size-attribute of vtyp. 
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• vtyp is a string type or a char type and expval is a quoted-character- 
constant. 

• vtyp is a packed array[l„/7] of char and expval is a string constant 
containing exactly n characters. 

If the index- type of the packed array of char is not \„n, but the array 
does have exactly n elements, no error will occur. However, the results 
are unspecified. 

Whenever assignment-compatibility is required and none of the above is true, 
either a compiler error or a run-time error occurs. 

3.5 The Type-Declarati(xv-Part 

Any program, procedure, or function that declares types contains a type- 
declaration-part, as shown in Chapter 2. 

Example of a type-declaration-part- 



type count = 


integer; 


range = 


integer; 


color = 


(red, yellow, green, blue); 


sex 


(male, female); 


year 


1900.. 1999; 


shape = 


(triangle, rectangle, circle); 


card = 


array [1.. 80] of char; 


str 


string[80]; 


polar = 


record r: real; theta: angle end; 


person = 


"personDetails; 


personDetails = record 


name. 


PirstName: str; 


age: 


Integer; 


married: boolean; 


father, 


, child, sibling: person; 


case s 


: sex of 


male 


: (enlisted, bearded: boolean); 


female: (pregnant: boolean) 


end; 




people = 


= file of personDetails; 


intfile = 


= file of integer; 



In the above example count, range, and integer denote identical types. The 
type year is compatible with, but not identical to, the types range, count, and 
integer. 
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Variables 



4.1 Variable-Declarations 

A variable-declaration consists of a list of Identifiers denoting new variables^ 
followed by their type. 



variable-declaration 



identifier-list 



-»(T>- H type > >Q ► 



4.2 



The occurrence of an identifier within the identifier-list of a variable- 
declaration declares it as a variable-identifier for the block in which the 
declaration occurs. The variable can then be referenced throughout the 
remaining lexical extent of that block, except as specified in Section 2.2.2. 

Examples of variable-cteclaratlons: 

X,y,z: real; 

tj: integer; 

k: 0..9; 

p^q,r: boolean; 

qperator: (plus, minus, times); 

a: array[0..63] of real; 

c: color; 

f : file of char; 

huel,hue2: set of color; 

pl,p2: person; 

rR,ml,m2: array[1..10,1..10] of real; 

coord: polar; 

pooltape: array [1.. 4] of tape; 

Variable-References 

A variable-reference denotes the value of a variable of simple-type or 
pointer-type, or the collection of values represented by a variable of 
structured-type. 



variable-reference 

► 



variable-identifier 



Til 



qualifier 



^ 



variable-identifier 



identifier 
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Syntax for the various kinds of qualifiers is given below. 

43 Quallfien 

As Shown above, a variable-reference is a variable-identifier followed by zero 
or more qualifiers. Each qualifier modifies the meaning of the variable- 
reference. 



Qualifier 



index 



field-designator 



"^ 



file-buffer-symbol 



^ 



^ pointer-object-symbol 



An array identifier with no qualifier is a reference to the entire array: 

xResults 

If the array identifier is followed by an index, this denotes a specific 
component of the array: 

xResults[curr8nt+l ] 

If the array component is a record, the index may be followed by a field- 
designator; in this case the variable-reference denotes a specific field within a 
specific array component. 

XResults [current+l 3 .link 

If the field is a pointer, the field-designator may be followed by the pointer- 
object-symbol, to denote the object pointed to by the pointer: 

xResults[current+i] .link " 

If the object of the pointer is an array, another index can be added to denote 
a component of this array (and so forth) 

XResults [ current +1 ]. link "[ 1 ] 

4.3.1 Arrays, Strings, and Indexes 

A specific component of an array variable is denoted by a variable- reference 
that refers to the array variable, followed by an index that specifies the 
component. 

A specific character within a string variable is denoted by a variable-reference 
that refers to the string variable, followed by an index that specifies the 
character position. 



IrKtex 



<S> 



I 



expression 



J 



<D-H- 
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Examples of incfexea arrays: 

in[i.j] 
a[i-J] 

Each expression in the index selects a component in the corresponding 
dimension of the array. The number of expressions must not exceed the 
number of index-types in the array declaration, and the type of each 
expression must be assignment-compatible with the corresponding index-type. 

In indexing a multi-dimensional array, you can use either multiple indexes or 
multiple expressions within an index. The two forms are completely equivalent. 
For example, 

ni[i][j] 

is equivalent to 
m[i.j] 

For array variables, each index expression must be assignment-compatible with 
the corresponding index-type specified in the declaration of the array-type. 

A string value can be indexed by only one index expression, whose value must 
be in the range I../?, where n is the current length of the string value. The 
effect is to access one character of the string value. 

WARNING 

When a string value is manipulated by assigning values to individual 
character positions, the dynamic length of the string is not maintained. 
For example, suppose that strval is declared as follows: 

strval: strlng[l0]; 

The memory space allocated for strval includes space for 10 char values 
and a number that will represent the current length of the string~i.e., 
the number of char values currently in the string. Initially, all of this 
space contains unspecified values. The assignment 

strval[l]:='F' 

may or may not work, depending on what the unspecified length happens 
to be. If this assignment works, it stores the char value T' in character 
position 1, but the length of strval remains unspecified. In other words, 
the value of slrval[l] is now T', but the value of strval is unspecified. 
Therefore, the effect of a statement such as writeln(strval) is 
unspecified. 

Therefore, this kind of string manipulation is not recommended. Instead, 
use the standard procedures described in Section 11.6. These procedures 
properly maintain the lengths of the string values they modify. 
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4.3.2 Records and Field-Designators 

A specific field of a record variable is denoted by a variable-reference that 
refers to the record variable^ followed by a field-designator that specifies the 
field. 



flelcf-c/eslpnator 



o- 



identifier 



Examples of fleia-designators: 

p2". pregnant 
coord. theta 

4.3.3 FUe-Buffen 

Although a file variable may have any number of components, only one 
component is accessible at any time. The position of the current component in 
the file is called the current file position See Sections 10.2 and 10.3 for 
standard procedures that move the current file position. Program access to the 
current component is via a special variable associated with the file, called a 
flle-nuffer 

The file-buffer is implicitly declared when the file variable is declared. If F 
is a file variable with components of type T, the associated file-buffer Is a 
variable of type T. 

The file-buffer associated with a file variable Is denoted by a variable- 
reference that refers to the file variable, followed by a qualifier called the 
file-buffer-symbol. 



file-tjuffer-syntol 



O 



Thus the file-buffer of file F is referenced by F . 

Sections 10.2 and 10.3 describe standard procedures that are used to move the 
current file position within the file and to transfer data between the file- 
buffer and the current file component. 

4.3.4 Pointers and Their Objects 

The value of a pointer variable is either nil, or a value that identifies some 
other variable, called the object of the pointer. 

The object pointed to by a pointer variable is denoted by a variable-reference 
that refers to the pointer variable, followed by a qualifier called the pointer- 
object-symbol. 



pointer-object-symbol 



O 



4-4 



Pascal Reference Manual VarJaOJes 

NOTTE 

Pointer values are created by the standard procedure new (see Section 
11.2.1), by the » operator (see Section 5.1.6), and by the standard 
procedure pointer (see Section 11.3.4). 

The constant nil (see Section 3.3) does not point to a variable. If you access 
memory via a nil pointer reference, the results are unspecified; there may not 
be any error indication. 

Examples of references to otfpcts of pointers: 
pi .sibling 
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Expressions consist of operators and operands^ i.e. variables, constants, set- 
constructors, and function calls. Table 5-1 shows the operator precedence: 

Table 5-1 
Precedence of Gperators 



Cperators 




Categories 


PiBceaefice 


», not 


highest 


unary operators 


», /, div, 
mod, and 


second 


"multiplying" operators 


+, -, or 


third 


"adding" operators & signs 


<=, >=, in 


lowest 


relational operaton 



The following rules specify the way in which operands are bound to operators: 

• When an operand is written between two operators of different precedence, 
it is bound to the operator with the higher precedence. 

• When an operand is written between two operators of the same precedence, 
it is bound to the operator on the left. 

Note that the order in which operations are performed is not specified. 

These rules are implicit in the syntax for expressions, which are built up from 
factors, terms, and simple-expressions. 

The syntax for a /ac7tor allows the unary operators © and not to be applied to 
a value: 



factor 



^ 



V£>^ 



variable-reference 



unsigned-constant 



^ 



function-call 



^ 



set-constructor 



>{T)-l^ expression 
-»(not)-» factor - 



K)> 



■^ 



^ 
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A function-call activates a function, and denotes the value returned Dy tne 
function (see Section 5.2). A set-constructor ^M\^\s,% a value of a set-type (see 
Section 5.3). An unsigned-const&it has the following syntax: 



unsigned-constant 



"T 



v^ 



's^ 



unsigned-number 



quoted-string-constant 



"^ 



constant-identifier 



> 



>(mr> 



k. 



Exmples of factors: 

X 

ax 

15 

(x+y+z) 

sin(x/2) 

[•A'..'F'.'a' 

not p 



•f ] 



{variable-reference } 
{pointer to a variable} 
{unsigned-constant } 
{sub-expression} 
{function-call} 
{set-constructor} 
{negation of a boolean} 



The syntax for a term allows the "multiplying" operators to be applied to 
factors: 



term 



^ 



factor 






-(dhr)4- 
-(mod)4- 



^ 



Examples of terms: 

x»y 

1/(1-1) 
p and q 
(x <= y) and (y < z) 
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The syntax for a sirrple-e)pwssion allows the "adding" operators and signs to 
be applied to terms: 



sinyle-expressi&i 



WlionK 



\ 



term 



^ 






Examples of slnpie-expressims: 

x+y 

-X 

huel + hue2 

i*j * 1 

The syntax for an expression allows the relational operators to be applied to 
simple-expressions: 

e)pression 



simple-expression 



■^ 






simple-expression 



Examples of expressions: 

X = 1.5 

p <= q 

p = q and r 

(i < J) = (J < k) 
c in huel 
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5.1 Operators 
5.1-1 Binary Operators: Order of Evaluation of Operands 

The order of evaluation of the operands of a binary operator is unspecified. 

5.1.2 Arithmetic Operators 

The types of operands and results for arithmetic binary and unary operations 
are shown in Tables 5-2 and 5-3 respectively. 

T*le 5-2 
Binary Arithmetic operations 



Cperatar 


Cperation 


Cperancf Types 


Type of R^ult 


+ 


addiUon 


integer, real, or 
longint 


integer, real, or 
longint 


- 


subtraction 


» 


multiplication 


/ 


division 


integer, real, or 
longint 


real 


div 


division with 
integer result 


integer or longint 


integer or longint 


mod 


modulo 


integer or longint 


intjeger 


Note: The symbols +^ -, and * are also used as set operators (see 
Section 5.1.4). 



Table 5-3 
Unary Arithmetic Operations (Signs) 



operator 


operation 


Cperana Types 


Type of Result 


■*■ 


identity 


integer, real, or 
longint 


same as operand 


- 


sign-negation 



Any operand whose type is subr, where subr is a subrange of some ordinal-type 
ordtyp, is treated as if it were of type ordtyp. Consequently an expression 
that consists of a single operand of type subr is itself of type ordtyp. 
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If doth the operands of the addition, subtraction, or multiplication operators 
are of type Integer or longint, the result is of type integer or longint as 
described in Section 3.1.1.2; otherwise, the result is of type leaL 

NQfTE 

See Appendix D for more information on all arithmetic operations with 
operands or results of type real. 

The result of the identity or sign-negation operator is of the same type as the 
operand. 

The value of 1 div j is the mathematical quotient of i/j, rounded toward zero 
to an integer or longint value. An error occurs if j-D. 

The value of 1 mod j is equal to the value of 

i - (i div j)-j 

The sign of the result of mod is always the same as the sign of 1. An error 
occurs if J-0. 

The predefined constant maxint is of type integer. Its value is 32767. This 
value satisfies the following conditions: 

• All whole numbers in the closed interval from -maxint- 1 to +maxint are 
representable in the type integer. 

• Any unary operation performed on a whole number in this interval will be 
correctly performed according to the mathematical rules for whole-number 
arithmetic. 

• Any binary integer operation on two whole numbers in this same interval 
will be correctly performed according to the mathematical rules for 
whole-number arithmetic, provided that the result is also in this interval. 
If the mathematical result is not in this interval, then the actual result is 
the low-order 16 bits of the mathematical result. 

• Any relational operation on two whole numbers in this same interval will be 
correctly performed according to the mathematical rules for whole-number 
arithmetic. 
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5.13 Boolean Qperaton 

The types of operands and results for Boolean operations are shown in Table 
5-4. 



Table 5-4 
Boolean Operations 



cperator 


cperatlon 


operana Types 


Type of Result 


or 


disjunction 


boolean 


boolean 


and 


conjunction 


not 


negation 



Whether a Boolean expression is completely or partially evaluated if its value 
can be determined Xs^i partial evaluation is unspecified. For example, consider 
the expression 

true or boolTst(x) 

where boolTst is a function that returns a boolean value. This expression will 
always have the value true, regardless of the result of boolTst(x)L The language 
definition does not specify whether the boolTst function is called when this 
expression is evaluated. This could be important if boolTst has side-effects. 

5.1.4 Set Operators 

The types of operands and results for set operations are shown in Table 5-5. 



Table 5-5 
Set Operations 



Operator 


Cperatlon 


Operand Types 


Type of Result 


■♦■ 


union 


compatible 
set-types 


(see S.l.a.l) 


- 


difference 


» 


intersection 
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5.1A1 Result Type in Set Operations 

The following ailes govern the type of the result of a set operation where one 
(or both) of the operands is a set of subr, where ordtyp represents any 
ordinal- type and subr represents a subrange of ordtyp: 

• If ordtyp is not the type integer^ then the type of the result is set of 
ordtyp. 

• If ordtyp is the type integer, then the type of the result is set of 0.4087 in 
the current implementation (D..32767 in a future implementation). This rule 
results from the limitations on set-types (see Section 3.2.3). 

5.1.5 Relational Operators 

The types of operands and results for relational operations are shown in Table 
5-6, and discussed further below. 

Table 5-6 
Relational Qpeiations 



operator 


Operation 


Oper&Td Types 


Type of Result 


- 


ec^ 


compatible set-, 
simple-, or 
pointer-types 
(& see below) 


boolean 


<> 


not equal 


< 


less 


compatible 
simple-types 
(& see below) 


> 


greater 


<- 


less/equal 


>« 


greater/equal 


<= 


subset of 


compatible 
set-types 


>- 


superset of 


in 


member of 


left operand: 
anj/ ordinal-tYpe T 
' rlgnfope^^ 
set of T 



5.1.5.1 Comparing Numbere 

When the operands of <, >, >-, or <- are numeric, they need not be of 
compatible type If one operand is real and the other is integer or longlnt 

NOTE 

See Appendix D for more information on relational operations with 
operands of type real. 
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5.13.2 Comparing Booleans 

If p and q are boolean operands, then p-q denotes tnelr equivalence and p<-q 
denotes the implication of q by p (because false<tiiie). Similarly, p<>q denotes 
logical "exclusive-or." 

5.1.53 Comparing Strings 

When the relational operators =,<>,<,>,<-, and > are used to compare 
strings (see Section 3.1.1.6), they denote lexicographic ordering according to the 
ordering of the ASCII character set. Note that any two string values can be 
compared since all string values are compatible. 

5.1.5.4 Comparing Sets 

If u and V are set operands, then u<-v denotes the inclusion of u in v, and 
u>=v denotes the inclusion of v in u. 

5.13.5 Testing Set Membership 

The in operator yields the value true if the value of the ordinal-type operand 
is a member of the set-type operand; otherwise it yields the value false. 

5.1.5-6 Comparing Packed Arrays of Char 

In addition to the operand types shown in the table, the - and <> operators can 
also be used to compare a packed array[lJM] of char with a string constant 
containing exactly N characters, or to compare two one-dimensional packed 
arrays of char of identical type. 

5.1.6 ©-Operator 

A pointer to a variable can be computed with the ©-operator. The operand 
and result types are shown in Table 5-7. 



Table 5-7 
Pointer Operation 



Cperator 


Operation 


Operana 


Type of Result 


9 


pointer 
formation 


variable, parameter, 
procedure, or 
function 


same as nil 



» is a unary operator taking a single variable, parameter, procedure, or 
function as its operand and computing the value of its pointer. The type of 
the value is equivalent to the type of nil, and consequently can be assigned to 
any pointer variable. 
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5.1.6.1 ©-Operator With a Variable 

For an ordinary variable (not a parameter), the use of » Is straightforward. For 
example, if we have the declarations 

type twochar = packed array [0..1] of char; 
var Int: integer; 

tiwcharptr: "tiwchar; 

then the statement 

tiwcharptr := aint 

causes twocharptr to point to iht Now twochaiptr" is a reinterpretation of 
the bit value of int as though it were a packed array[CLl] of char. 

The operand of » cannot be a component of a packed variable. 

5.1.6.2 e-Operator With a Value Parameter 

When • is applied to a formal value parameter, the result is a pointer to the 
stack location containing the actual value. Suppose that foo is a formal value 
parameter in a procedure and fooptr is a pointer variable. If the procedure 
executes the statement 

fooptr := afoo 

then fooptr" is a reference to the value of foa Note that if the actual- 
parameter is a variable-reference, fooptr" is not a reference to the variable 
itself; it is a reference to the value taken from the variable and stored on the 
stack. 

5.1.6.3 ©-Operator With a variable Parameter 

When » is applied to a formal variable parameter, the result is a pointer to 
the actual-parameter (the pointer is taken from the stack). Suppose that fum 
is a formal variable parameter of a procedure, fie is a variable passed to the 
procedure as the actual-parameter for fum, and fumptr is a pointer variable. 

If the procedure executes the statement 

fumptr := afum 

then fumptr is a pointer to fie. fumptr" is a reference to fie itself. 

5.1.6.4 ©-Operator With a Procedure or Function 

It is possible to apply » to a procedure or a function, yielding a pointer to the 
entry-point Note that Pascal provides no mechanism for using such a pointer. 
Currently the only use for a procedure pointer is to pass it to an assembly- 
language routine, which can then JSR to that address. 

If the procedure pointed to is in the local segment, © returns the current 
address of the procedure's entry point If the procedure is in some other 
segment, however, © returns the address of the jump table entry for the 
procedure. 
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In logical memory mapping (see Workshop User's Gulcte for the Lisa), the 
procedure pointer is always valid. 

In physical memory mapping, code swapping may change a local-segment 
procedure address without warning, and the procedure pointer can become 
invalid. If the procedure is not in the local segment, the jump-table entry 
address will remain valid despite swapping because the jump table is not 
moved. 

5.2 Function-Calls 

A function-call specifies the activation of the function denoted by the 
function-identifier. If the conesponding function-declaration contains a list of 
formal-parameters, then the function-call must contain a corresponding list of 
actual-parameters. Each actual-parameter is substituted for the corresponding 
formal-parameter. The correspondence is established by the positions of the 
parameters in the lists of actual and formal parameters respectively. The 
number of actual-parameters must be equal to the number of formal 
parameters. 

The order of evaluation and binding of the actual-parameters is unspecified. 



fijncUon-cail 
^ 



function-identifier 



T^i 



actual-parameter-list 



acu/al -parameter-list 



<(> 



r 



actual -parameter 



O 



T 



<)> 



actual-parameter 



expression 



variable- reference 



procedure-identifier 



^ function-Identifier 



^ 



> 



^-— ► 



A function-identifier is any identifier that has been declared to denote a 
function. 
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Examples of function-calls: 

suin(^63) 

gcd(147,k) 

sin(x+y) 

eof(f) 

ordCf") 

5.3 Set-Constnicton 

A set-constructor denotes a value of a set-type, and is formed by writing 
expressions within [brackets]. Each expression denotes a value of the set 

set-constructor »(jy,^ ^/f)_^ 



'v - ^ momhor— nrni in -. • — ^ 



member-group 



^ O- ^ 



njeoTder-moup 



expression 



W(Ty-» expression -^ 



The notation [ ] denotes the empty set, which belongs to every set-type. Any 
member-group x„y denotes as set members the range of all values of the base- 
type In the closed interval x to y. 

If x is greater than y, then x..y denotes no members and [x.y] denotes the 
empty set 

All values designated in member-groups in a particular set-constructor must be 
of the same ordinal-type. This ordinal-type is the base-type of the resulting 
set. If an integer value designated as a set member is outside the limits given 
in Section 3.2.3 (0..4D87 in the current Implementation), the results are 
unspecified. 

Exanples of set-constn^tors: 

[red, c, green] 

[1, 5, 10.. k mod 12, 23] 

[•A*..'Z', 'a'..'z', chr(xcode)] 
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6.1 Simple Statements 6-1 

6.1.1 AssigiTnent-Statements 6-1 

6.1.2 Procedure-Statements 6-2 

6.1.3 Goto-Statements 6-3 

62 Structured-Statements 6-4 

6.2.1 Compound-Statements 6-4 

6.2.2 Conditional-Statements 6-4 

6.2.2.1 If-Statements 6-5 

6.2.2.2 Case-Statements 6-5 

6.2.3 Repetitive-Statements 6-6 

6.2.3.1 Repeat-Statements 6-7 

6.2.3.2 While-Statements 6-7 

6.2.3.3 For-Statements 6-8 

6.2.4 With-Statements 6-10 



statements 



statements denote algorithmic actions^ and are executable. They can be 
prefixed by labels; a labeled statement can be referenced by a goto-statement. 

statement 



^ label \ -^(Jy^ 



-^ 



^ simple-statement 



^ structured-statement 



J 



J 



¥ digit-sequence 



A digit-sequence used as a label must be in the range 0..9999^ and must first 
be declared as described in Section 2.1. 

6.1 Simple Statements 

A simple-Statement is a statement that does not contain any other statement. 



simpJe-statement 



T 



assignment-statement 



v^ 



procedure-statement 



■^ 



goto-statement 



L. 



6.1.1 Assignment-Statements 

The syntax for an assignment-statement is as follows: 



assJgnfiTent-statenjent 



TD 



vari^le-reference 



function-identifier 



»(1-) — » expression 



The assignment-statement can be used in two ways; 

• To replace the current value of a variable by a 
expression 

• To specify an expression whose value is to be returned by a function. 



To replace the current value of a variable by a new value specified as an 
expression 



6-1 



Pascal Reference Manual Statements 



The expression must de assignment-compatible with the type of the variable or 
the result-type of the function. 

NOTE 

If the selection of the variable involves indexing an array or taking the 
object of a pointer, it is not specified whether these actions precede or 
follow the evaluation of the expression. 



Exmiples of asslg^vnent-statements: 

X : = y*z; 

p := (l<=i) and (i<100); 
i := sqr(k) - (i*j); 
huel := [blue,succ(c)]; 

6.L2 Procedure-Statements 

A procedure-Statement serves to execute the procedure denoted by the 
procedure-identifier. 



pnx^t/m-st3tenwnt 

^^ actual-Darameter-list -^ 



-> 



procedure-identifier 



(A procedure-identifier is simply an identifier that has been used to declare a 
procedure.) 

If the procedure has formal-parameters (see Section 7.3), the procedure- 
statement must contain a list of actual-parameters that are bound to the 
corresponding formal-parameters. The number of actual-parameters must be 
equal to the number of formal parameters. The correspondence is established 
by the positions of the parameters in the lists of actual and formal parameters 
respectively. 

The rules for an actual-parameter AP depend on the corresponding formal- 
parameter FP: 

• If FP is a value parameter, AP must be an expression. The type of the 
value of AP must be assignment-compatible with the type of PP. 

• If FP is a variable parameter, AP must be a variable-reference. The type 
of AP must be identical to the type of FP. 

• If FP is a procedural parameter, AP must be a procedure-identifier. The 
type of each formal-parameter of AP must be identical to the type of the 
corresponding formal-parameter of FP. 
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• If FP is a functional parameter, AP must be a function-identifier. The type 
of each formal-parameter of AP must be identical to the type of the 
corresponding formal-parameter of FP, and the result-type of AP must be 
identical to the result-type of FP. 

NOTE 

The order of evaluation and binding of the actual parameters is 
unspecified. 

Examples of procedure-statements: 

prlntheading; 
transpos8(a,n,m); 
bisect (fct^ -1 . 0^ +1 . 0, x); 

6.1.3 Goto-Statements 

A goto-statement causes a jump to another statement in the program, namely 
the statement prefixed by the label that is referenced in the goto-statement 



qoto-st3tement »(^^^^r)-»f"iibil 



NOTE 



The constants that introduce cases within a case-statement (see Section 
6.2.2.2) are not labels, and cannot be referenced In goto-statements. 



The following restrictions apply to goto-statements: 

• The effect of a jump into a structured statement from outside of the 
structured statement is unspecified. 

• The effect of a jump between the then part and the else part of an If- 
statement is unspecified. 

• The effect of a jump between two different cases within a case-statement 
is unspecified. 
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62 Stiuctured-Statements 

Structured-statements are constructs composed of other statements that must 
be executed either conditionally (conditional-statements^ repeatedly 
(repetitive-statements), or in sequence (compound-statement or with-statement). 



structured-statement 



"T 



^ conditional-statement 



compound-statement 



"H^ repetitive-statement 



^ wilh-statement 



62..1 Compound-Statements 

The compound-statement specifies that its component statements are to be 
executed in the same sequence as they are written. 



compound-statement 
» ( begin} 



c 



statement 



O 



J 



<^ 



Example of compound-statement: 

begin 

2 := X; 

X := y; 

y := z 
end 

An important use of the compound-statement is to group more than one 
statement into a single statement, in contexts where Pascal syntax only allows 
one statement. The symbols begin and end act as "statement brackets." 
Examples of this will be seen in Section 6.2.3.2. 

6.2.2 Conditional-Statements 

A conditional-statement selects for execution a single one (or none) of its 
component statements. 



a^Jtlmal-statenjent 



u 



If-stalement 



case-statement 
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6.2.2.1 If-Statements 

The syntax for if-statements is as follows: 



if-statement 



<¥)-#► 



expression 



W (then 



D 



^ 



statement 



^~»\^elseJ-» statement -^ 



The expression must yield a result of type tx)0leaa If the expression yields 
the value true, the statement following the then is executed. 

If the expression yields false and the else part is present the statement 
following the else is executed; if the else part is not present, nothing is 
executed. 

The syntactic ambiguity arising from the construct: 

If el then 
if e2 then si 
else s2 

is resolved by interpreting the construct as being equivalent to: 

if el then begin 
if e2 then si 
else s2 
end 

Exannples of if-statements: 

if X < 1.5 then z := x*y else z := 1.5; 
if pi <> nil then pi := pi ".father; 

6.2J2.2 Case-Statements 

The case-statement contains an expression (the selectoli and a list of 
statements. Each statement must be prefixed with one or more constants 
(called case-constant^, or with the reserved word otherwise. All the case- 
constants must be distinct and must be of an ordinal-type that is compatible 
with the type of the selector. 



case-stat^wfit 



{^case)— » expression 



of 





otherwise-clause 



>(^id)-» 
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case 



Tl 



constant 



O 



I 



O-l 



statement 



otf^rwjse-clmjs^ 



-»(7}-> { otlierviseJ -» statement 



The case-statement specifies execution of the statement prefixed by a case- 
constant equal to the current value of the selector. If no such case-constant 
exists and an otherwise part is present, the statement following the word 
otherwise is executed; if no otherwise part is present, nothing is executed. 

Exmples of case-statements: 



case operj 


ate 


)r 


of 


plus: 


X 


; = 


x+y; 


minus: 


X 


: = 


x-y; 


times: 


X 


: = 


x*y 


end 








case i of 








1: 




X 


:= sln(x); 


2: 




X 


:= COS(x); 


3.4,5: 




X 


:= exp(x); 


otherwise 


X 


:= ln(x) 


end 









IMPLEMENTATION NOTE 



In the current Implementation, the case-statement will not work 
correctly if any case-constant is of type longint or the value of the 
selector is of type longint 



6.2.3 Repetitive-Statements 

Repetitive-statements specify that certain statements are to be executed 
repeatedly. 



repetitive-statement 



"^ 



repeat-statement 



while-statement 



"^ 



for-statement 



\^ 
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6.23.1 Repeat-Statements 

A repeat-Statement contains an expression which controls the repeated 
execution of a sequence of statements contained within the repeat-statement 



repeat-statement 

^(j^^L 



Y 



Statement 



O 



I 



»(until3 — ► expression 



The expression must yield a result of type Doolean. The statements between 
the symbols repeat and until are repeatedly executed until the expression 
yields the value true on completion of the sequence of statements. The 
sequence of statements is executed at least once, because the expression is 
evaluated after execution of the sequence. 

Exanples of repeat-statements: 

repeat 
k := 1 mod J; 
1 := J; 

until j = 



repeat 

process(f " 

get(f) 
until eof(f ) 



); 



6.2.3.2 While-Statements 

A While-Statement contains an expression which controls the repeated 
execution of one statement (possibly a compound-statement) contained within 
the while-statement. 



while-statement 



-►{^ while} — ► e>q3ression 



statement 



The expression must yield a result of type boolean. It is evaluated t)efore 
contained statement is executed. The contained statement is repeatedly 
executed as long as the expression yields the value trua If the expression 
yields false at the beginning, the statement is not executed. 



the 
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The while-statement: 
while b do body 

is equivalent to: 

if b then repeat 

body 
until not b 

Examples of while-statements: 

iihile a[i] <> x do i := i+l 

while i>0 do begin 

if odd(i) then z := z*x; 

i := i div 2; 

X := sqr(x) 
end 

while not eof (f ) do begin 

process(f " ); 

get(f) 
end 

6^3.3 For-Statements 

The for-statement causes one contained statement (possibly a compound- 
statement) to be repeatedly executed while a progression of values is assigned 
to a variable called the contwl-variabla 



for-statement 

»{ ^for^ )— » control-variable — •Kj=/-^ initial-value 

C 



D 




(to> 



cbwnto 



final-value -^^*)-^ statement 



cmtrol-t/arlatue 



^ variable-Identifier 



initial-value 



e>pression 



final-value 



^ expression 
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The control-variable must be a variable-identifier (without any qualifier). It 
must be local to the innermost block containing the for-statement, and must 
not be a variable parameter of that block. The control-variable must be of 
ordinal-type^ and the initial and final values must be of a type compatible with 
this type. 

The first value assigned to the control-variable Is the Inltlal-value. 

If the for-statement Is constructed with the reserved word to, each successive 
value of the control-variable Is the successor (see Section 3.1) of the previous 
value, using the Inherent ordering of values according to the type of the 
control-variable. When each value Is assigned to the control-variable. It Is 
compared to the final-value; If It Is less than or equal to the final value, the 
contained statement Is then executed. 

If the for-statement Is constructed with the reserved word downto, each 
successive value of the control-variable Is the predecessor (see section 3.1) of 
the previous value. When each value Is assigned to the control-variable, it Is 
compared to the final-value; if it is greater than or equal to the final value, 
the contained statement Is then executed. 

If the value of the control-variable is altered by execution of the repeated 
statement, the effect Is unspecified. After a for-statement Is executed, the 
value of the control-variable Is unspecified, unless the for-statement was 
exited by a goto. Apart from these restrictions, the for-statement 

for V := el to 92 do body 

Is equivalent to: 

begin 
tenpl := el; 
ten|)2 := e2; 

if tenpl <= teinp2 then begin 
V := tenpl; 
body; 

ifhile V o teinp2 do begin 
V := siicc(v); 
body 
end 
end 
end 
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and the for-statement: 

for V := el downto e2 do txxly 

is equivalent to: 

begin 
tenpl := el; 
teirp2 := e2; 

if tempi >= tefnp2 tfien begin 
V := tenpl; 
body; 

i»hile V <> teinp2 do begin 
V := pred(v); 
body 
end 
end 
end 

where tempi and temp2 are auxiliary variables of the host type of the variable 
V that do not occur elsewhere in the program. 

Examples of for-statements: 

for i := 2 to 63 do if a[i] > max then max := a[i] 

for i := 1 to n do for j := 1 to n do 
begin 
X := 0; 

for k := 1 to n do X := X + ml[i,k]*m2[k, j]; 
m[i, j] := X 
end 

for c := red to blue do q(c) 

6.2.4 WIth-Statements 

The syntax for a with-statement is 

wiUi-statEfnent 

— »( ^wlthV ^ record-variable-reference -^v—^doy-^ 




O 



T 



statement 



(A record-variable-reference is simply a reference to some record variable.) 
The occurrence of a record-variable-reference in a with-statement affects the 
way the compiler processes variable-references within the statement following 
the word da Fields of the record-variable can be referenced by their field- 
identifiers, without explicit reference to the record-variable. 
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Exanpie of with-statement- 

with date do if month = 12 then begin 

month := 1; 

year := year + 1 
end 
else month := month + 1 

This is equivalent to: 

if date. month = 12 then begin 

date. month := 1; 

date.year := date. year + 1 
end 
else date. month := date. month + 1 

Within a with-statement, each variable-reference is checked to see if it can 
be interpreted as a field of the record. Suppose that we have the following 
declarations: 

type recTyp = retard 

foo: integer; 
bar: real 
end; 

var baz: recTyp; 
foo: integer; 

The identifier foo can refer both to a field of the record variable baz and to a 
variable of type integer. Now consider the statement 

with baz do begin 
foo := 36; {which foo is this?} 

end 

The foo in this with-statement is a reference to the field baz.foo, not the 
variable foo. 

The statement: 

with vl,v2, ... vn do s 

is equivalent to the following "nested" with-statements: 

with VI do 
with v2 do 

with vn do s 
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If vn in the above statements is a field of both vl and v2, it is interpreted to 
mean \/2.vn, not vl.vn. The list of record-variable-references in the wlth- 
statement is checked from right to left 

If the selection of a variable in the record-variable-list involves the indexing 
of an array or the de-referencing of a pointer, these actions are executed 
before the component statement is executed. 

WARNING 

If a variable in the record-variable-list is a pointer- reference, the value 
of the pointer must not be altered within the with-statement. If the 
value of the pointer is altered, the results are unspecified. 

Exmiple of (jTsafe with-statement using pointer-reference: 

with ppp' do begin 

new(ppp); {Don't do this ...} 

ppp:=xxx; {... or this} 

end 
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7.1 Procedure-Declarations 

A procedure-declaration associates an identifier with part of a program so that 
it can be activated dy a procedure-statement. 

proceciure-aeclaration 

procedure-heading "MT)^ procedure-body >(T) — ^ 



procedunsf-ixdy 



^ 



block 



-»( ^ forward 
-»(^exterr^J- 



is^ 



The procedure-heading specifies the Identifier for the procedure, and the 
formal parameters (if any). 

pjioc&.tJie-t^acilty 



-»(^ procedure J — •► identifier 



^ 



formal-parameter-list 



rr 



The syntax for a formal -parameter-list is given in Section 7.3. 

A procedure is activated by a procedure-statement (see Section 6.1.2), which 
gives the procedure's identifier and any actual-parameters required by the 
procedure. The statements to be executed upon activation of the procedure 
are specified by the statement-part of the procedure's block. If the 
procedure's identifier is used in a procedure-statement within the procedure's 
block, the procedure is executed recursively. 
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Example of a pwcedure-cfeclaration: 

procedure readlnteger (var f : text; var x: integer); 
var value^digitValue: integer; 
begin 
while (f * = ' ') and not eof(f) do get(f); 
value := 0; 

iphile (f" in ['O'-.'S']) and not eof(f) do begin 
digitValue := ord(f ") - ordCO'); 
value := 10«value + digitValue; 
get(f) 
end; 

X := value 
end; 

A procedure-declaration that has forward instead of a block is called a 
forward declaration Somewhere after the forward declaration (and in the 
same block), the procedure is actually defined by a defining declaration--^ 
procedure-declaration that uses the same procedure-identifier, omits the 
formal-parameter-list, and includes a block. The forward declaration and the 
defining declaration must be local to the same block, but need not be 
contiguous; that is, other procedures or functions can be declared between 
them and can call the procedure that has been declared forward. This permits 
mutual recursion. 

The forward declaration and the defining declaration constitute a complete 
declaration of the procedure. The procedure is considered to be declared at 
the place of the forward declaration. 

Exarrple of forward declaration: 

procedure walterCntn: integer); {forirard declaration} 
forward; 

procedure clara(X/ y: real); 
begin 

»aiter(4. 3); {OK because waiter is forward declared} 

end; 

procedure waiter; {defining declaration} 
begin 

ciara(8.3, 2.4); 

end; 

A procedure-declaration that has external instead of a block defines the Pascal 
interface to a separately assembled or compiled routine (a PROC in the case 
of assembly language). The external code must be linked with the compiled 
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Pascal host program before execution; see the iVo/ksnop User's Guide for the 
Lisa for details. 

Example of an external procedure-declaration: 

procedure makescreen( index: Integer); 
external; 

This means that makescreen is an external procedure that will be linked to the 
host program before execution. 

IMPLEMENTATION NOTE 

It is the programmer's responsibility to ensure that the external 
procedure is compatible with the external declaration in the Pascal 
program; the current linker does no checking. 



NOTE 

This Pascal (unlike Apple II and Apple III Pascal) does not allow a 
variable parameter of an external procedure or function to be declared 
without a type. To obtain a similar effect, use a formal-parameter of 
pointer- type, as in the following example: 

type bigpaoc = packed array[0.. 32767] of char; 
bigpaocptr = ''blgpaoc; 

procedure whatever (bytearray: bigpaocptr); 
external; 

The actual-parameter can be any pointer value obtained via the ^ 
operator (see Section 5.1.6). For example, if dots is a packed array of 
boolean, it can be passed to whatever by writing 
iphatever(adots) 



This description of external procedures also applies to external functions. 
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12 Function-Declarations 

A function-declaration serves to define a part of the program that computes 
and returns a value of simple-type or pointer-type. 

function-declaration 

function-heading -^Q)^ function-body -^J) — ^ 



function-t)ocfy 



^ 



^ 



block 



-l^forvart 
-»( ext.emal )- 



\^ 



The function-heading specifies the identifier for the function, the formal 
parameters (if any), and the type of the function result 



function-headin g » ( ^;]^;^5^>^rH15^^ 



c 



D 



formalrparameter-list 



VT 



(T)-> result-type 



result-type 



ordinai-type-identlfier 



^ 



real -type- identifier - 



pointer-type-identifier 



The syntax for a formal-parameter-list is given in Section 7.3. 

A function is activated by the evaluation of a function-call (see Section 5.2), 
which gives the function's identifier and any actual-parameters required by the 
function. The function-call appears as an operand in an expression. The 
expression is evaluated by executing the function, and replacing the function- 
call with the value returned by the function. 

The statements to be executed upon activation of the function are specified by 
the statement-part of the function's block. This block should normally contain 
at least one assignment-statement (see Section 6.1.1) that assigns a value to 
the function-identifier. The result of the function is the last value assigned. 
If no such assignment-statement exists, or if it exists but is not executed, the 
value returned by the function is unspecified. 
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If the functim's identifier is used in a function-call within the function's 
block, the function is executed recursively. 

Examples of function-declarations: 

function inax(a: vector; n: integer); real; 
var x: real; i: integer; 
begin 

X :- a[i]; 

f or i := 2 to n do if X < a[i] then x := a[i] 

max := X 
end; 

function power (x: real; y: integer): real; { y >= 0} 
var w^z: real; i: integer; 
begin 
• := X; z := 1; i := y; 
while i > do begin 
{z*(r«»i) = X *« y } 
if odd(i) then z := z*w; 
i := i div 2; 
w := sc|r(w) 
end; 

{z = x»*y > 
power := z 
end; 

A function can be declared forward in the same manner as a procedure (see 
Section 7.1 above). This permits mutual recursion. 

A function-declaration that has external Instead of a block defines the Pascal 
Interface to a separately compiled or assembled external routine (a J=^UNC in 
the case of assembly language). See the explanation in Section 7.1 above. 

7.3 Parameten 

A formal-parameter-list may be part of a procedure-declaration or 
function-declaration, or it may be part of the declaration of a procedural or 
functional parameter. 

If it is part of a procedure-declaration or function-declaration, it declares the 
formal parameters of the procedure or function. Each parameter so declared 
is local to the procedure or function being declared, and can be referenced by 
its identifier in the block associated with the procedure or function. 

If it is part of the declaration of a procedural or functional parameter, it 
declares the formal parameters of the procedural or functional parameter. In 
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this case there is no associated block and the identifiers of parameters in the 
formal-parameter-list are not significant (see Sections 7.3.3 and 7.3.4 below). 



fojmaJ-parametBr-JJst 



parameter-declaration 



^ procedure-heading 



^♦^ 



function-heading 



O 



7^^ 



^ 



<D-^ 



parmiefer-aecJaimJm ^ | nienUfier"^^nirV »Q-» r type-idenUfier 



var 



There are four kinds of parameters: value parameter^ variable parameters, 
pr(KecHjral par&fieters, and fUixitional parameters They are distinguished as 
follows: 

• A parameter-group preceded by var is a list of variable paranneters. 

• A parameter-group without a preceding var is a list of value parameters. 

• A procedure-heading or function-heading denotes a procedural or functional 
parameter; see Sections 7.3.3 and 7.3.4 below. 

NOTE 

The types of formal-parameters are denoted by type-identifiers. In 
other words^ only a simple identifier can be used to denote a type in a 
formal-parameter-list. To use a type such as arra>(0^255] of char as 
the type of a parameter, you must declare a type-identifier for this 
type: 

type charray = grrayfo. .255] of char; 

The identifier chanay can then be used in a formal-parameter-list to 
denote the type. 
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NOTE 

The word file (for an "untyped" file) is not allowed as a type-identifier 
in a parameter-declaration, since it is a reserved word. To use a 
parameter of this type, declare some other identifier for the type file 
—for example, 

type phyle = f ile; 

The identifier phyle can then be used in a formal-parameter-list to 
denote the type file. 

7.3.1 Value Paranneters 

For a value-parameter, the conesponding actual -parameter in a procedure- 
statement or function-call (see Sections 5.2 and 6.1.2) must be an expression, 
and its value must not be of file-type or of any structured-type that contains 
a file-type. The formal value-parameter denotes a variable local to the 
procedure or function. The current value of the expression is assigned to the 
formal value-parameter upon activation of the procedure or function. The 
actual-parameter must be assignment-compatible with the type of the formal 
value-parameter. 

7.3.2 Variable Parameters 

For a variable-parameter, the corresponding actual-parameter in a procedure- 
statement or function-call (see Sections 5.2 and 6.1.2) must be a variable- 
reference. The formal variable-parameter denotes this actual variable during 
the entire activation of the procedure or function. 

Within the procedure or function, any reference to the formal variable- 
parameter is a reference to the actual-parameter itself. The type of the 
actual-parameter must be Identical to that of the formal variable-parameter. 

NOTE 

If the reference to an actual variable-parameter involves indexing an 
array or finding the object of a pointer, these actions are executed 
before the activation of the procedure or function. 

Components of variables of any packed structured type (including string-types) 
cannot be used as actual variable parameters. 

7.3.3 Procedural Parameters 

When the formal-parameter is a procedure-heading, the corresponding actual- 
parameter in a procedure-statement or function-call (see Sections 5.2 and 6.1.2) 
must be a procedure-identifier. The identifier in the formal procedure-heading 
represents the actual procedure during execution of the procedure or function 
receiving the procedural parameter. 
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Example of procedural parameters: 

program passProc; 
var i: integers- 
procedure a(procedure x) {x is a formal procedural parameter.} 
begin 
writeCAtxiut to call x '); 
X {call the procedure passed as parameter} 
end; 

procedure b; 
begin 

write('In procechjre b") 
end; 

function c(procedure x): integer; 
begin 
X; {call the procedure passed as parameter} 

C:=2 

end; 

begin 

a(b); {call a, passing b as parameter} 

i:= c(b) {call Cs passing b as parameter} 
end. 

If the actual procedure and the formal procedure have formal-parameter-lists, 
the formal-parameter-lists must be compatible (see Section 7.3.5). However, 
only the identifier of the actual procedure is written as an actual parameter; 
any formal-parameter-list is omitted. 

Ex&rple of prcx;&k/ral parameters with their own fojunal-par&rwter-lists: 

program test; 
procedure xAsPar(y: integer); 
begin 

*»ritelnCy='s y) 
end; 

procedure callProc(procedure xAgain(z: integer)); 
begin 

xAgain(l) 
end; 

begin {body of program} 

callProc(xAsPar) 
end. 

If the procedural parameter, upon activation, accesses any non-local entity (by 
variable-reference, procedure-statement, function-call, or label), the entity 
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accessed must be one that was accessible to the procedure when the procedure 
was passed as an actual parameter. 

To see what this means, consider a procedure pp which is known to another 
procedure, flntPasser. Suppose that the following sequence takes place: 

1. firstPasser is executing. 

2. firstPasser calls a procedure named flnlReceiver, passing pp as an 
actual parameter. 

3. firstReceiver calls secondReceiver, again passing pp as an actual 
parameter. 

4. secondReceiver calls pp (first execution of pp). 

5. secondReceiver calls thirdRecelver, again passing pp as an actual 
parameter. 

6. thirdReceiver calls fintPasser (indirect recursion), and passes pp to 
firstPasser as an actual parameter. 

7. firstPasser (executing recursively) calls pp (second execution of pp). 

Thus the procedure pp is called first from secondReceiver, and then from the 
second (recursive) execution of firstPasser. 

Suppose that pp accesses an entity named xxx, which is not local to pp; and 
suppose that each of the other procedures has a local entity named xxx. 

Each time pp is called, which xxx does it access? The answer is that in eacf) 
case, pp accesses the xxx that is local to the first execution of firstPasser— 
that is, the xxx that was accessible when pp was originally passed as an actual 
parameter. 

7.3.4 Functional Paramelen 

When the formal parameter is a function-heading, the actual-parameter must 
be a function-identifier. The identifier in the formal function-heading 
represents the actual function during the execution of the procedure or 
function receiving the functional parameter. 

Functional parameters are exactly like procedural parameters, with the 
additional rule that corresponding formal and actual functions must have 
Identical result-types. 

73.5 Parameter List Compatibility 

Parameter list compatibility is required of the parameter lists of corresponding 
formal and actual procedural or functional parameters. 
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Two formal-parameter-lists are compatible if they contain the same number of 
parameters and if the parameters in corresponding positions match. Two 
parameters match if one of the following is true: 

• They are both value parameters of Identical type. 

• They are both variable parameters of JcK&itlcal type. 

• They are both procedural parameters with compatible parameter lists. 

• They are both functional parameters with compatible parameter lists and 
identical result-types. 
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Programs 



8.1 Syntax 

A Pascal program has the form of a procedure declaration except for its 
heading and an optional uses-clausa 

progr&ii 

program-heading ~MV/" 



t: 



uses-clause 



w^ 



block 



progi'am-neacfJng 



— »( program) -» identifier -^r 7— «► 

■"-{T)-**' program-parameters ■^KJy'^^ 



piajicm-paiBmete/s 



identifier-list 



uses-clause 



<W> 



identifier- list 



The occurrence of an identifier immediately after the word program declares it 
as the program's identifier. 

The uses-clause identifies all units required by the prograffn, including units 
that it uses directly and other units that are used by those units. 

8.2 Program-Parameters 

Currently, any program-parameters are purely decorative and are totally 
Ignored by the compiler. 

8.3 Segmentation 

The code of a program's main body is always placed in a run-time segment 
whose name is a string of blanks (the "blank segment"). Any other block can 
be placed in a different segment by using the $S compiler command (see 
Chapter 12 and Appendix A). If no $S command is used In the program, all 
code is placed in the blank segment. Code from a program can be placed in 
the same segment with code from a regular-unit, but it cannot be mixed with 
code from an intrinsic-unit (see Chapter 9). 
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Units 



A unit is a separately compiled, non-executable object file that can be linked 
with other object files to produce complete programs. There are two kinds of 
units, called regular-units wi:i^ intrinsic-units. In the current implementation of 
the Workshop, you can use intrinsic-units that are provided, but you cannot 
write new ones. 

Each unit used by a program (or another unit) must be compiled, and its object 
file must be accessible to the compiler, before the host program (or unit) can 
be compiled. 

9.1 Regular-Units 

Regular-units can be used as a means of modularizing large programs, or of 
making code available for incorporation in various programs, without making 
the source available. 

When a program or unit (called the host) uses a regular-unit, the linker Inserts 
a copy of the compiled code from the regular-unit Into the host's object file. 

By default, the code copied from the regular-unit is placed In the blank 
segment (see Chapter 8). The code of the entire unit, or of blocks within the 
unit, can be placed In one or more different segments by using the $S compiler 
command (see Chapter 12). 

9.1.1 Writing Regular-Units 

The syntax for a regular-mlt is: 



'■^'^-^l » j unit-heading \ -MJ) 



Q 



) 



interface-part ■> implementation-part -►(end 



utiit-tyeaaifiq ^^^^y^ 



Identifier 
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units 



interface-part ^ ( ^^^^ 



J 



^ uses-Clause 



^ 



^ constant-declaration-part 



^ 



D 



D 



^^ type-declaratlon-part 



D 



"•^ variable-declaration-part 



r- 



D 



^ procedure-and-functlon-declaration-part 



1. 



impJementat/on-part^ f- ^^^^^^^^ y 



J 



^ constant-declaration-part 



r 



S^ type-declaration-part 



D 



^ 
^ 



D 



varisdDle-declaration-part 



<• 



D 



^ procedure-and-function-declaration-part 



^^--^ 



The interface-part declares constants, types, variables, procedures, and 
functions that are "public," i.e. available to the host 

The host can access these entities just as if they had been declared in the 
host Procedures and functions declared in the interface-part are abbreviated 
to nothing but the procedure or function name, parameter specifications, and 
function result-type. 

NOTE 

Since the interface-part may contain a uses-clause, a unit can use 
another unit (see Section 9.3). 
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The implementation-part, which follows the last declaration in the interface- 
part, begins by declaring any constants, types, variables, procedures, or 
functions that are "private," i.e. not available to the host 

The public procedures and functions are re-declared in the implementation- 
part. The parameters and function result types are omitted from these 
declarations, since they were declared in the interface-part, and the procedure 
and function blocks, omitted in the interface-part, are included in the 
implementation-part. 

In effect, the procedure and function declarations in the interface are like 
forward declarations, although the forward directive is not used. Therefore, 
these procedures and functions can be defined and referenced in any sequence 
in the implementation. 

NOTES 

There is no "initialization" section in Pascal units on the Lisa (unlike 
Apple II and Apple III Pascal). If a unit requires initialization of its 
data, it should define a public procedure that performs the initialization, 
and the host should call this procedure. 

Also note that global labels cannot be declared in a unit 

A short example of a unit is: 

unit Simple; 

INTERFACE {public Objects declared} 

const FlrstValue=l; 
procedure AddOne(var Incr: integer); 
function Addl(Incr : integer) : integer; 
IMPLEMENTAnON 
procedure AddOne; {note lack of parameters...} 
begin 

Incr:=Incr+l 
end; 
function Addl; {...and lack of function result type} 

begin 

Addl:=lncr+1 
end 
end. 

9.1.2 Using Regular-units 

The syntax for a uses-clause is given in Section 8.1. Note that in a host 
program, the uses-clause (if any) must immediately follow the program- 
heading. In a host unit, the uses-clause (if any) immediately follows the 
symbol Interface. Only one uses-clause may appear in any host program or 
unit; it declares all units used by the host program or unit 

see Section 9.3 for the case where a host uses a unit that uses another unit 
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It is necessary to specify the file to be searched for regular units. The $U 
compiler command specifies this file. See Chapter 12 for more details. 

Assunnc that the example unit Simple (see above) is compiled to an object file 
named APPL:S1MPLE.0BJ. The following is a short program that uses Simple. 
It also uses another unit named Other^ which is in file APPL:OTHER.0BJ. 



program CallSlmple; 
uses {$U APPL:SIMPLE.OBJ> 
Simple^ 

{$U APPLtOTHER.OBJ) 
Other; 
var i: integer; 
begin 
i:=FirstValue; 
wite(*i+l is ',Addl(i)); 
i»rite(xyz(i)) 
end. 



{file to search for units} 
{use unit Sinple} 
{file to search for units} 
{use unit Other} 



{FirstValue is from Sinple} 
{Addl is defined in Sinple} 
{xyz is defined in Other} 



9.2 Intrinsic-units 

The only intrinsic-units you can use are the ones provided with the Workshop 
software. 

Intrinsic-units provide a mechanism for Pascal programs to share common code, 
with only one copy of the code in the system. The code is kept on disk, and 
when loaded into memory it can be executed by any program that declares the 
intrinsic-unit (via a uses-clause, the same as for regular-units). 

By default, the system looks up all intrinsic-units in the system intrinsics 
library file, INTRINSIC.LIB. All intrinsic-units are referenced in this library, 
so the $U filename compiler command is not needed with intrinsic-units. 

9.3 Units that Use Other Units 

As explained above, the uses-clause in the host must name all units that are 
used by the host. Here "used" means that the host directly references 
something in the interface of the unit Consider the following diagram: 



Host Program 
uses unitA, unitB; 



unitA 



Interface 
uses urutC; 



implementation 



unite 



interface 



implementation 



unite 



interface 



implementation 
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The host program directly references the interfaces of unitA and unitB; the 
uses-clause names doth of these units. The implementation-part of unitA also 
references the interface of unite, but it is not necessary to name unite in the 
host-program's uses-clause. 

In some cases, the uses-clause must also name a unit that Is not directly 
referenced by the host. The following diagram is exactly like the previous one 
except that this time the Interface of unltA references the interface of unite, 
and unite must be named in the host-program's uses-clause. Note that unite 
must be named before unitA. 



Host Program 
uses unite, unltA, 
unitB; 



unitA 



interface 
uses unite; 



implementation 



unitB 



interface 



implementation 



unite 



Interface 



implementation 



In a case like this, the documentation for unltA should state that unite must 
be named in the uses-clause before unitA 
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This chapter describes the standard C'buiit-in") I/O procedures and functions of 
Pascal on the Lisa. 

Standard procedures and functions are predeclared. Since all predeclared 
entities act as if they were declared in a "block" surrounding the program, no 
conflict arises from a declaration that redefines the same identifier within the 
program. 

NOTE 

Standard procedures and functions cannot be used as actual procedural 
and functional parameters. 

This chapter and Chapter 11 use a modified BNF notation, instead of syntax 
diagrams, to indicate the syntax of actual-parameter-lists for standard 
procedures and functions. 

Example: 

Parameter List- ne«(p [, tl, ... t/?]) 

This represents the syntax of the actual-parameter-list of the standard 
procedure new, as follows: 

• p, tl, and t/7 stand for actual-parameters. Notes on the types and 
interpretations of the parameters accompany the syntax description. 

• The notation tl, ... t/7 means that any number of actual-parameters can 
appear here, separated by commas. 

• Square brackets [ ] indicate parts of the syntax that can be omitted. 

Thus the syntax shown here means that the p parameter is required. Any 
number of t parameters may appear, with separating commas, or there may be 
no t parameters. 

10.1 IntroducUon to I/O 

This section covers the I/O concepts and procedures that apply to all file types. 
This includes the types text (see Section 10.3) and "untyped" files (see Section 
10.4). 

To use a Pascal file variable (any variable whose type is a file-type), it must 
be associated with an external file. The external file may be a named 
collection of information stored on a peripheral device, or (for certain file- 
types) it may be the peripheral device itself. 

The association of a file variable with an external file is made by opening the 
file. N\ existing file is opened via the reset procedure, and a new file is 
created and opened via the rewrite procedure. 
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NOTE 

Pascal on the Lisa does not provide automatic I/O checking. To check 
the result of any particular I/O operatioa use the ioresult function 
described in Section 10.1.6. 

iai.l Device Types 

For purposes of Pascal I/O^ there are two types of peripheral devices: 

• A flle-stwcturecl device is one that stores files of data^ such as a diskette. 

• A character device is one whose input and output are streams of individual 
bytes, such as the Lisa screen and keyboard or a printer. 

iai.2 External File Species 

There are three "species" of external files that can be used in Pascal I/O 
operations: 

• A dataflle is any file that is stored on a file-structured device and was 
/%7^ originally created in association with a file variable of type text 

• A textfile is a file that is stored on a file-structured device and was 
originally created in association with a file variable of type text Textfiles 
are stored in a specialized format (see Section 10.3). 

• A character aevlce can be treated as a file. 

Table 10-1 summarizes the effects of all possible combinations of different file 
variable types and external file species. The "ordinary cases" in the table 
reflect the basic intent of the various file-types. Other combinations, such as 
block-oriented access to a textfile via a variable of type file, are legal but 
may require cautious programming. 
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Table 10-1 

Combinations of File Variable Types witli External File Species 

and Cateigories 



var f: file of 

someType; 



var f : text; 



var f : file; 



Ordinary case. 



datafile 



After reset 
f * - 1st record 
file. 



(Textfile format 
assumed!) After 
reset**, f * Is 
unspecified. 



Ordinary case. 



Block access. 



textfile 



(Textfile format 
not assumed!) 
After reset*, 
f * = 1st record 
of file (as 
declared). 



Ordinary case. 
Textfile format 
assumed. After 
reset, f * is 
unspecified. 



(Textfile format 
not assumed!) 
Block access. 



character 
device 



After reset, 
f * = 1st char, 
from device 
(system waits for 
it!). I/O error if 
file record type 
not byte-sized. 



Ordinary case. 
After reset, 
f " Is unspeci- 
fied (no wait 
for input char). 



Block access, 
if allowed by 
device. 



* In these cases, the Jarestat function will return a "warning" 
(i.e., a negative numt)er) immediately after the reset operation 



iai3 The Reset Procedure 

Opens an existing file. 

Parameter List reset(f, title) 

1. f is a variable-reference that refers to a variable of file-type, 
must not be open. 



The file 



title is an expression with a string value. The string should be a valid 
pathname for a file on a file-structured device, or a pathname for a 
character device. 
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NOTE 

Both parameters are required (unlike Apple II and Apple III Pascal, 
where the second parameter is optional). 

Reset(t title) finds an existing external file with the pathname title, and 
associates f with this external file. (If there is no existing external file with 
the pathname title, an I/O error occurs; see Section 10.1.6.) 

If title is the pathname of a character device, then 

• Eof(f) becomes false. 

• If f is of type text, the value of f " is unspecified. The next read or readln 
on f will wait until a character is available for input, and begin reading 
with that character. 

• If f is of type file and the device is one that allows block access, there is 
no file buffer variable f" and the "current file position" is set to the first 
block (block 0) of the file. If the device does not allow block access, an 
I/O error occurs (see Section 10.1.6). 

• If f is not of type text or file, its component-type must be a "byte-size" 
type such as the type -128..127. Note that char is not a byte-size type! If 
the component- type of f is not byte-size, an I/O error occurs (see Section 
10.1.6). 

If no 1/0 error occurs, the system waits until a character is available from 
the device and then assigns the character's 8-bit code to f ". 

If title is the pathname for an existing file on a file-structured device, then 

• Eof(f) becomes false if the external file is not empty. If the external file 
is empty, eof(f) becomes true. 

• If f is not of type text or file, reset sets the "current file position" to the 
first record in the external file, and assigns the value of this record to the 
file buffer variable f ". If the external file is a textfile, the ioresult 
function will return a negative number as a warning (see Section 10.1.6). 

• If f is of type text, the value of f " is unspecified. If the file is a textfile, 
the next read or readln on f will begin at the first character of f. If the 
file is a datafile, it will be treated as if it were a textfile (see Section 
10.3) and the ioresult function will return a negative number as a warning 
(see Section 10.1.6). 

• If f is of type file, there is no file buffer variable f " and the "current file 
position" is set to the first block (block 0) of the file. 
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iai.4 The Rewrite Procedure 

Creates and opens a new file. 

Parameter List: rewite(f^ title) 

1. f is a variable-reference that refers to a variable of file-type. 

2. title is an expression with a string value. The string should be a valid 
pathname for a file on a file-structured device^ or a pathname for a 
character device. 

If f is already open, an I/O error occurs (see Section 10.1.6). 

If title is the pathname of a character device, then 

Eof(f) becomes false. 

Rewrite(f, title) simply associates f with the device and opens f. 

The status of the device is not affected. 

The value of f * becomes unspecified. 
If title is the pathname for a new file on a file-structured device, then 

Eof(f) becomes true. 

Rewrite(f, title) creates a new external file with the pathname title, and 
associates f with the external file. This is the only way to create a new 
external file. 

The species of the new external file is set according to the type of f~ 
"textfile" for type text, or "datafile" for any other type. 

The value of f " becomes unspecified. 

If f is not of type file, the "current file position" is set to just before the 
first record or character position of the new external file. 

If f is of type file, the "current file position" is set to block (the first 
block in the file). 

If f is subsequently closed with any option other than lock or crunch (see 
Section 10.1.5), the new external file is discarded at that time. Closing f 
with lock or cnnch is the only way to make the new external file 
permanent. 

If title is the pathname of an existing external file, the existing file will be 
discarded only when f is subsequently closed with the lock or cnnch option 
(see Section 10.1.5). 

Unspecified effects are caused if the current file position of a file f is altered 
while the file-buffer f * is an actual variable parameter, or an element of the 
record-variable-reference list of a with-statement, or both. 
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10.1.5 "ITie Close Procedure 

Closes a file. 

Parameter List- close(f [, option]) 

1. f is a variable-reference that refers tx) a variable of file-type. 

2. option (may be omitted) is an identifier from the list given below. If 
omitted^ the effect is the same as using the identifier normal. 

Close(f^ option) closes f, if f is open. The association between f and its 
external file is broken and the file system marks the external file "closed". If 
f is not open^ the close procedure has no effect 

The option parameter controls the disposition of the external file^ if it is not a 
character device. If it is a character device^ f is closed and the status of the 
device is unchanged. 

The identifiers that can be used as actual-parameters for option are as follows: 

• noimal ~ If f was opened using rewrite, it is deleted from the directory. 
If f was opened with reset it remains in the directory. This is the default 
option, in the case where the option parameter is omitted. 

• lock ~ If the external file was opened with rewrite, it is made permanent 
in the directory. 

If f was opened with rewrite and a title that matches an existing file, the 
old file is deleted (unless the safety switch is "on"). If the old file has the 
safety switch "on," it remains in the directory and the new file is deleted. 

If f was opened with reset a normal close is done. 

• purge ~ The external file is deleted from the directory (unless the safety 
switch is "on"). In the special case of a file that already exists and is 
opened with rewrite, the original file remains in the directory, unchanged. 

• crunch ~ This is like lock except that it locks the end-of-file to the point 
of last access; i.e., everything after the last record or character accessed is 
thrown away. 

All closes regardless of the option will cause the file system to mark the 
external file "closed" and will make the value of f * unspecified. 

If a program terminates with a file open (i.e., if close is omitted), the system 
automatically closes the file with the normal option. 

NOTE 

If you open an existing file with reset and modify the file with any 
write operation, the contents are imrmediately changed no matter what 
close option you specify. 
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iajL6 TTie loresmt Function 

Pascal on the Lisa does not provide automatic I/O checking. To check the 
result of any particular I/O operation^ you must use the ioresult function. 

Result type: integer 

Parameter List- no parameters 

Ioresult returns an integer value which reflects the status of the last com- 
pleted I/O operation. The codes are given in the Workshop User's Gulcfe for the 
Lisa Note that the code indicates successful completion^ positive codes 
indicate errors^ and negative codes are "warnings" (see Table lO-l). 

Note that the codes returned by ioresult are not the same as the codes used in 
Apple II and /\pple III Pascal. 

NOTES 

The read^ readln, write, and writeln procedures described in Section 10.3 
may actually perform multiple I/O operations on each call. After one of 
these procedures has executed, ioresult will reUjrn a code for the status 
of the last of the multiple operations. 

Also, beware of the following common error in diagnostic code: 

read(foo); 

•rlteln( * ioresult= ' , ioresult) 

The intention is to write out the status of the read operation, but 
instead the status written out will be that of the write operation on the 
string 'ioresult-'. 

iai.7 TDe Eof Function 

Detects the end of a file. 

Result Type: boolean 

Parameter List- eof [(f)] 

1. f is a variable-reference that refers to a variable of file-type. 

If the parameter-list is omitted, the function is applied to the standard file 
input (see Section 10.3). 

After a get or put operation, eof(f) returns taie if the current file position is 
beyond the last external file record, or the external file contains no records; 
otherwise, eof(f) returns false, specifically, this means the following: 

• After a get, eof(f) returns true if the get attempted to read beyond the last 
file record (or the file is empty). 

• After a put, eoftO returns true if the record written by the put is now the 
last file record. 



10-7 



Pascal Reference Manual Input/Output 

If f is a character device, eof(f) will always return false. 

See Section 10.3 for the behavior of eof(f) after a read or readln operation. 

NOTE 

Whenever eof(f) is true, the value of the file buffer variable f " is un- 
specified. 

10.2 Recoid-Qriented I/D 

This section covers the get, put, and seek procedures, which perform record- 
oriented I/O; that is, they consider a file to be a sequence of variables of the 
type specified in the file-type. These procedures are not allowed with files of 
type fila 

The effects of get and put are unspecified with files of type text, and seek has 
no effect with files of type text The text type is supported by specialized 
procedures described in Section 10.3. 

102.1 The C3et Procedure 

Reads the next record in a file. 

Parameter List get(f) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

If eof(f) is false, get(f) advances the current file position to the next file 
record, and assigns the value of this record to f . If no next component 
exists, then eof(f) becomes true, and the value of f " becomes unspecified. 

If eof(f) is true when get(f) is called, then eof(f) remains true, and the value of 
f " becomes unspecified. 

If the external file is a character device, eof(f) is always false and there is no 
"current file position." In this case, get(f) waits until a value is ready for input 
and then assigns the value to f *. 

10.2.2 The Put Procedure 

Writes the current record in a file. 

Parameter List put(f) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

If eof(f) is false, put(f) advances the current file position to the next file 
record and then writes the value of f ' to f at the new file position. If the 
new file position is beyond the end of the file, eofl(f) becomes true, and the 
value of f * becomes unspecified. 

If eof(f) is true, put(f) appends the value of f " to the end of f and eof[f) 
remains true. 
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If the external file is a character device, eof(f) is always false, there is no 
"current file position;* and the value of f * is sent to the device. 

NOTE 

If put is called immediately after a file is opened with reset, the put 
will write the second record of the file (since the reset sets the 
current position to the first record and put advances the position before 
writing). To get around this and write the first record, use the seek 
procedure (see Section 10.2.3). 

10.2.3 The Seek Procedure 

Allows access to an arbitrary record in a file. 

Parameter List- seek(f, n) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

2. n is an expression with an integer value that specifies a record number in 
the file. Note that records in files are numbered from 0. 

If the file is a character device or is of type text, seek does nothing. 
Otherwise, seek(f, n) affects the action of the next gel or put from the file, 
forcing it to access file record n instead of the "next" record. Seek(f^ n) does 
not affect the file-buffer f ". 

A get or put must be executed between seek calls. The result of two con- 
secutive seeks with no intervening get or put is unspecified. Immediately after 
a seek(f, n), eof(f) will return false; a following get or put will cause eof to 
return the appropriate value. 

NOTE 

The record number specified in a seek call is not checked for validity. 
If the number Is not the number of a record in the file and the program 
tries to get the specified record, the value of the file-buffer becomes 
unspecified and eof becomes true. 

103 Text-Oriented lA) 

This section describes Input and output using file variables of the standard type 
text Note that In Pascal on the Lisa, the type text Is distinct from file of 
char (see Section 3.2.4). 

When a text file Is opened, the external file Is Interpreted In a special way. It 
Is considered to represent a sequence of characters, usually formatted Into 
lines by CR characters (ASCII 13). 

The Lisa keyboard and the workshop screen appear to a Pascal program to be 
built-in files of type text named input and output respectively. These files 
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need not be declared and need not be opened with reset or rewrite, since they 
are always open. 

When a program Is taking Input from input, typed characters are echoed on the 
Workshop screen. In addition to the input file, the Lisa keyboard is also 
represented as the character device -KEYBOARD. To get keyboard input 
without echoing on the screen, you can open a file variable of type text with 
-KEYBOARD as the external file pathname. 

Other interactive devices can also be represented in Pascal programs as files of 
type text 

When a text file is created on a file-structured device, the external file is a 
textfile. It contains information other than the actual sequence of characters 
represented, as follows: 

• The stored file is a sequence of 102a-byte pagesi 

• Each page contains some number of complete lines of text and is padded 
with null characters (ASCII 0) after the last line. 

• Two 512-byte heac^r blocks are also present at the beginning of the file. 

• A sequence of spaces in the text may be compressed into a two-byte code, 
namely a OLE character ip^OW 16) followed by a byte containing 32 plus 
the number of spaces represented. 

All of this special formatting is invisible to a Pascal program if the file is 
accessed via a file variable of type text (but visible via a file variable of any 
other file-type). 

Certain things that can be done with a record-structured file are impossible 
with a file variable of type text 

• The seek procedure does nothing with a file variable of type text 

• The effects of get and put are unspecified with a file variable of type text 

• The contents of the file buffer variable are unspecified with a file variable 
of type text 

• A file variable of type text that is opened with reset cannot be used for 
output, and one opened with rewrite cannot be used for input. Results are 
unspecified if either of these operations is attempted. 

In place of these capabilities, text-oriented I/O provides the following: 

• Automatic conversion of each input CR character into a space. 

• The eoln function to detect when the end of an input line has been 
reached. 

• The read procedure, which can read char values, string values, packed array 
of char values, and numeric values (from textual representations). 
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• The write procedure^ which can write char values^ string values, packed 
array of char values, numeric values, and lx»lean values (as textual 
representations). 

• Line-oriented reading and writing via the readln and writeln procedures. 

• TlTe page procedure, which outputs a form-feed character to the external 
file. 

• Automatic conversion of input DLE-codes to the sequences of spaces that 
they represent. Note that output sequences of spaces are not converted to 
DLE-codes. 

• Automatic skipping of header blocks and null characters during input 

• Automatic generation of textfile header blocks, and automatic padding of 
textfile pages with null characters on output 

10.3.1 The Read Procedure 

Reads one or more values from a text file into one or more program variables. 

Parameter LlsL- read( [f, ] vl [, v2, . . . v/7] ) 

The syntax of the parameter-list of read allows an indefinite number of 
actual-parameters. Consecutive actual-parameters are separated by commas, 
just as in a normal parameter-list 

1. f (may be omitted) is a variable-reference that refers to a variable of 
type text The file must be open. If f is omitted, the procedure reads 
from the standard text file Input, which represents the Lisa keyboard. 

2. vl ... v/7 are input variables Each is a variable parameter, used as a 
destination for data read from the file. Each input variable must be a 
variable-reference that refers to a variable of one of the following types: 

• char, integer, or longint (or a subrange of one of these) 

• real 

• a string-type or a packed array of char type. 

These are the types of data that can be read (as textual representations) 
from a file. At least one input variable must be present. 

Read[f^vU..,v/7) is equivalent to: 

begin 
read(f,vl); 

read(f,v/7) 
end 
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NPTE 

Read can also be used to read from a file fil that Is not a text file. In 
this case iead(fllp() Is equivalent to: 

begin 

X := fll"; 

get(fil) 
end 



103.1.1 Read with a Char Variable 

If f is of type text and v is of type char, the following things are true 
immediately after read(f,v> 

• Eof(f) will return true If the read attempted to read beyond the last 
character in the external file. 

• Eoln(f) will return true, and the value of v will be a space, if the character 
read was the CR character. Eoln(f) will also return true if eof(f) is tiue. 

ia3.l.2 Read with an Integer or Longint variable 

If f is of type text and v is of type integer, subrange of integer, or longint, 
then read(f,v) implies the reading from f of a sequence of characten that form 
a signed whole number according to the syntax of Section 1.4 (except that 
hexadecimal notation is not allowed). If the value read is assignment- 
compatible with the type of v, it is assigned to v; otherwise an error occurs. 

In reading the sequence of characters, preceding blanks and CRs are skipped. 
Reading ceases as soon as a character is reached that, together with the 
characters already read, does not form part of a signed whole nunnber. 

An error occurs if a signed whole number is not found after skipping any 
preceding blanks and CRs. 

If f is of type text, the following things are true immediately after read(f,v) 

• Eof(f) will return tine if the last character in the numeric string was the 
last character in the external file. 

• Eoln(f) will return true if the last character in the numeric string was the 
last character on the line (not counting the CR character). Eolnff) will also 
return true if eof(f^ is true. 

ia3.L3 Read with a Real variable 

If f is of type text and v is of type real, then read(f>/) implies the reading 
from f of a sequence of characters that represents a real value. The real 
value is assigned to the variable v. 

In reading the sequence of characters, preceding blanks and CRs are skipped. 
Reading ceases as soon as a character is reached that, together with the 
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characters already read, does not form a valid representation. A "valid 
representation" is either of the following: 

• A finite rea, integer, or longint value represented according to the 
signed-numder syntax of Section 1.4 (except that hexadecimal notation is 
not allowed). An integer or longint value is converted to type real 

• An infinite value or Nan represented as described in Appendix D. 

An error occurs if a valid representation is not found after skipping any 
preceding blanks and CRs. 

immediately after read(f,v) where v is a real variable, the status of eof(fD and 
eoln(f) are the same as for an integer variable (see Section 10.3.1.2 above). 

103.1.4 Read with a String variable 

If f is of type text and v is of string-type, then read(f,v) implies the reading 
from f of a sequence of characters up to but not including the next CR or 
the end of the file. The resulting character-string Is assigned to v. An error 
occurs if the number of characters read exceeds the size attribute of v. 

NOTE 

Read with a string variable does not skip to the next line after reading, 
and the CR is left waiting in the input buffer. For this reason, you 
cannot use successive read calls to read a sequence of strings, as they 
will never get past the first CR ~ after the first read, each subsequent 
read will see the CR and will read a zero-length string. 

Instead, use readln to read string values (see Section 10.3.2). Readln 
skips to the beginning of the next line after reading. 

The following things are true immediately after read(f,v) 

• Eof(f) will return true if the line read was the last line in the file. 

• Eoln(f) will always return taie. 

10.3.1.5 Read with a Packed Array of Char variable 

If f is of type text and v is a packed array of char, then read(f,v) implies the 
reading from f of a sequence of characters. Characters are read into 
successive character positions in v until all positions have been filled, or until 
a CR or the end of the file is encountered. If a CR or the end-of-file is 
encountered, it Is not read Into v; the remaining positions In v are filled with 
spaces. 
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ia3J? TTie Readin Procedure 

The readin procedure is an extension of read. Essentially it does the same 
thing as read, and then skips to the next line in the input file. 

Parameter List' The syntax of the parameter list of readin is the same as that 
of read, except as follows: 

• A readin call with no input variables is allowed. Example: 

readme sourcef lie) 

• The parameter-list can be omitted altogether. 

If the first parameter does not specify a file, or if the parameter-list is 
omitted, the procedure reads from the standard file input, which represents the 
Lisa keyboard. 

Readln(fX with no input-variables, causes a skip to the beginning of the next 
line (if there is one, else to the end-of-file). 

Readin can onlyx^ used on a text file. Except for this restriction, 
reaclln(f,vl,™,v/7) is equivalent to: 

begin 

read(f,vl, ...,v/7); 

readln(f) 
end 

The following things are true immediately after readln(f,v), regardless of the 
type of V: 

• Eof(f) will return true if the line read was the last line in the external file. 

• Eoln(f) will always return false. 

103.3 The Write Procedure 

Writes one or more values to a text file. 

Parameter List- wlte([f, ] pi [, p2, ... p/?]) 

The syntax of the parameter list of write allows an Indefinite number of 
actual-parameters. 

1. f (may be omitted) is a variable-reference that refers to a variable of 
type text The file must be open. If f is omitted, the procedure writes to 
the standard file output, which represents the Workshop screen. 

2. pi ... p/7are output-specs Each output-spec includes an output 
expression, whose value is to be written to the file. As explainied below, 
an output-spec may also contain specifications of field-width and number 
of decimal places. Each output expression must have a result of type 
integer, longint, real, boolean, char, a string-type, or a packed array of 
char type. These are the types of data that can be written (as textual 
representations) to a file. At least one output-spec must be present. 
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Write(f4)1^4)/7) is equivalent to: 

begin 
iirlte(f,pl); 

wite(f,p/7) 
end 

Immediately after write(fX both eof(f) and eoln(f) will return true. 

NOTTE 

Write can also be used to write onto a file fU that is not a text file. 
In this case wrlte(fll^) is equivalent to: 

begin 

fU* := X; 

put(fll) 
end 

103.3.1 Output-Specs 

Each output-spec has U« form 

OutExpr [ : MlnWidth [ : DecPlaces] ] 

where OutExpr is an output expression. MinWidth and DecPlaces are 
expressions with integer or longint values. 

MlnWidth specifies the minimum field widths with a default value that 
depends on the type of the value of OutExpr (see below). MinWidth should be 
greater than zero; otherwise^ the results are unspecified. Exactly MlnWidth 
characters are written (using leading spaces if necessary), except when OutE)^r 
has a mn^ric value that requires more than MinWidth characters; in this 
case, enough characters are written to represent the value of OutExpr. 

DecPlaces specifies the number of decimal places in a fixed-point repre- 
sentation of a real value. It can be specified only if OutExpr has a real value, 
and if MinWidth is also specified. If DecPlaces is not specified, a floating- 
point representation is written. 

1033.2 Write with a Char value 

If OutExpr has a char value, the character is written on the file f. The default 
value for MinWidth is one. 

10.3.33 Write with an Integer or Longint value 

If OutExpr has an integer or longint value, its decimal representation is written 
on the file f. The default value for MinWidth is 8. The representation consists 
of the digits representing the value, prefixed by a minus sign if the value Is 
negative, and any leading spaces that may be required to satisfy MinWidth. If 
the representation requires more than MinWidth characters, MinWidth is 
ignored. 
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1033.4 Write with a Real V^ue 

If QutExpr has a real value^ the default value for MlnWidth is 12. 

If OutExpr has an infinite value, it is output as a string of at least two "+" 
characters or at least two "-" characten. If OutExpr is a NaN, it is output as 
the character string "NaN", possibly followed by a string of characters enclosed 
by single-quotes. See Section 10.3.3.5 for details on string output 

If OutExpr has a zero value, it is represented as "0" or "-0". 

If OutExpr has a finite value, its decimal representation is written on the file 
f. This representation is the nearest possible decimal representation, depending 
on MinWldth and DecPlaces. If the unrounded value is exactly halfway 
between two possible representations, the representation whose least significant 
digit is even Is written out. 

If DecPlaces is not specified, a floating-point representation is written as 
follows: 

If MinWidth is less than 6, then its value is set to 6 (internally). This is the 
minimum usable width for writing a floating-point representation. 

If the sign of the value of OutExpr Is negative, a minus sign is written; 
otherwise, a space is written. 

If MlnWidth > 8, the significant digits are written with one digit to the left 
of the decimal point and (MinWldth - 7) digits to the right of the decimal 
point. 

If MinWidth < 8, the most significant digit is written and the decimal point 
is omitted. 

The exponent is written as the letter "E", an explicit "♦" or "-" sign, and 
two digits. 

If DecPlaces is specified, a fixed-point representation is written as follows: 

Enough leading spaces are written to satisfy MlnWidth. 

If the value is negative, the minus sign "-" is written; if it is not negative, 
a space is written. 

If DecPlaces > 0, the significant digits are written with the Integer part of 
the value to the left of the decimal point. The next DecPlaces digits are 
written to the right of the decimal point 

If DecPlaces < 0, only the Integer part of the value Is written and no 
decimal point Is written. 

ia3.35 Write with a String Value 

If the value of OutExpr is of string type with length L, the default value for 
MinWidth Is L If MinWidth>-L, the value Is written on the file f preceded by 
(MInWidth-L) spaces. If MinWidth<L, the first MinWidth characten of the 
string are written. 
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103.3^ Write with a Packed Array of Char v^ue 

If E is of type packed array of char, the effect Is the same as writing a string 
whose length is the number of elements in the array. 

ia3.3.7 Write with a Boolean value 

If the value of OutExpr is of type txnlean, the string " TRUE" (with a leading 
space) or the string "FALSE" is written on the file f. The default value of 
MinWldth is 5. If Mlnwidth>5, leading spaces are added; if MinWldth<5, the 
first MlnWidth characters of the string are written. This is equivalent to: 

•rite(f, • TRUE'zMinWldth) 

or 
•rite(f, 'FALSE' .-MinWldth) 

ia3.4 TTie Wrlteln Procedure 

The wrlteln procedure is an extension of write. Essentially it does the same 
thing as write, and then writes a CR character to the output file (ending the 
line). 

Parameter List The syntax of the parameter list of writeln is the same as 
that of write, except as follows: 

• A writeln call with no output-specs is allowed. Example: 

inritelnCoutputfile) 

• The parameter-list can be omitted altogether. 

If the first parameter does not specify a file, or if the parameter-list is 
omitted, the procedure writes to the standard file output, which represents the 
Workshop screen. 

Writeln(f) writes a CR character to the file f. 

Writeln can onlyXye used on a text file. Except for this restriction, 
writeln(f4)l^^/7) is equivalent to: 

begin 

i»rite(f,pl, ...,p/7); 

wlteln(f) 
end 

Immediately after writeln(f% both eof(f) and eoln(f) will return true. 

ia3.5 The Eoln Function 
Result Type: boolean 

Parameter List- eoln[(f)] 

1. f is a variable-reference that refers to a variable of type text The file 
must be open. 

The actual-parameter-list can be omitted entirely. In this case, the function is 
applied to the standard file input (the Lisa keyboard). 
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Eoln(f) returns true "if tJie end of a line has been reached in f." The meaning 
of this depends on whether the external file is a character device, on which I/O 
procedure was executed last, and on what type of variable was used to receive 
an input value. For details, see Sections 10.3.1 through 10.3.4. 

The end of the file is considered to be the end of a line; therefore eoln(t^ will 
return true whenever eof(f) is true. 

10.3.6 The Page Procedure 
Parameter List- page(f) 

1. f is a variable-reference that refers to a variable of type text The file 
must be open. 

The actual-parameter f cannot be omitted. Page(f) outputs a form-feed 
character to the file f. This will cause a skip to the top of a new page when 
f is printed. 

Note that page(output) sends a form-feed to the Workshop screen, but in 
general this will not clear the screen. For methods of clearing the screen, see 
the Workshop User's Gulcfe for the Lisa . 

1G3.7 Keyboard Testing and Screen Cursor Control 
103.7.1 TTie Keypress Function 

Tests the Lisa keyboard to see if it has a character awaiting input 

Parameter List- no parameters . 

Result Type: booleaa 

Keypress returns true if a character has been typed on the Lisa keyboard but 
has not yet been read, or false otherwise. This is done by testing the 
typeahead queue; if the queue is empty, keypress is false, otherwise it is trua 

ia3.7.2 The Gotoxy Procedure 

Moves the Workshop screen cursor to a specified location on the screen. 

Parameter List: gotoxyCx;, y) 

1. X is an expression with an integer value. If x < 0, the value will be 
used; if X > 79, the value 79 will be used. 

2. y is an expression with an integer value. If y < 0, the value will be 
used; if y > 31, the value 31 will be used. 

Gotoj^X, y) moves the cursor to the point (x,y) on the screen. Note that the 
point (0,0) is the upper left comer of the screen. 

10.4 Untyped File I/O 

Untyped file I/O operates on an "untyped file," i.e., a variable of type file (no 
component type), /^n untyped file is treated as a sequence of 512-byte blocks; 
the bytes are not type-checked but considered as raw data This can be useful 
for applications where the data need not be interpreted at all during I/O 
operations. 
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The blocks in an untyped file are considered to be nunnbered sequentially 
starting with 0. The system keeps track of the ojrrent block nufrtxr;V[\\% is 
block innmediately after the file is opened. Each time a block is read^ the 
current block number is incremented. By default^ each I/O operation begins at 
the current block number; however^ an arbitrary block number can be specified. 

An untyped file has no file-buffer, and it cannot be used with get, put, or any 
of the text-oriented I/O procedures. It can only be used with reset, rewrite, 
close, eof, and the blockread and blockwrite functions described below. 

To use untyped file I/O, an untyped file is opened with reset or rewrite, and 
the blockread and blockwrite functions are used for input and output 

10.4.1 TTie Blockread Function 

Reads one or more 512-byte blocks of data from an untyped file to a program 
variable, and returns the number of blocks read. 

Result Type: Integer 

Parameter List- blockread(f, databuf, count [, blocknum]) 

1. f is a variable-reference that refers to a variable of type file. The file 
must be open. 

2. databuf is a variable-reference that refers to the variable into which the 
blocks of data will be read. The size and type of this variable are not 
checked; if it is not large enough to hold the data, other program data 
may be overwritten and the results are unpredictable. 

3. count is an expression with an integer value. It specifies the maximum 
number of blocks to be transferred. Blockread will read as many blocks 
as it can, up to this limit. 

4. blocknum (may be omitted) is an expression with an integer value. It 
specifies the starting block number for the transfer. If it is omitted, the 
transfer begins with the current block. Thus the transfers are sequential 
if the blocknumber parameter is never used; if a blocknumber parameter 
is used, it provides random access to blocks. 

Blockread(f, databuf, count, blocknum) reads blocks from f into databuf, starting 
at block blocknum. Count is the maximum number of blocks read; if the 
end-of-file is encountered before count blocks are read, the transfer ends at 
that point The value returned is the number of blocks actually read. 

If the last block in the file was read, the current block number is unspecified 
and eof(f) is tiua Otherwise, eof(f) is false and the current block number is 
advanced to the block after the last block that was read. 
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10.4.2 The Blockwrite Ftixjtion 

Writes one or more 512-byte blocks of data from a program variable to an 
untyped file, and returns the number of blocks written. 

Result Type: integer 

Parameter List: blocki»rite(f, databuf, count \, blocknum]) 

1. f is a variable-reference that refers to a variable of type file. The file 
must be open. 

2. databuf is a variable-reference that refers to the variable from which the 
blocks of data will be written. The size and type of this variable are not 
checked. 

3. count is an expression with an integer value. It specifies the maximum 
nunnber of blocks to be transferred. Blockwrite will write as many blocks 
as it can, up to this limit. 

4. blocknum (may be omitted) is an expression with an integer value. It 
specifies the starting block number for the transfer. If it is omitted, the 
transfer begins with the current block. Thus the transfers are sequential 
if the blocknumber parameter Is never used; if a blocknumber parameter 
is used. It provides random access to blocks. 

Blockwrite(f, databuf, count, blocknum) writes blocks into f from databuf, 
starting at block blocknum. Count is the maximum number of blocks written; 
if disk space runs out before count blocks are written, the transfer ends at 
that point. The value returned is the number of blocks actually written. 

If disk space ran out, the current block number is unspecified. Otherwise, the 
current block number is advanced to the block after the last block that was 
written. 

NOTE 

Unlike Apple II and Apple III Pascal, this Pascal does not allow 
blockwrite to write a block at a position beyond the first position after 
the current end of the file. In other words, you cannot create a block 
file with gaps in it. 
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This chapter describes all the standard C*built-in") procedures and functions in 
Pascal on the Lisa^ except for the I/O procedures and functions described in 
Chapter 10. 

Standard procedures and functions are predeclared. Since all predeclared 
entities act as if they were declared in a block surrounding the program, no 
conflict arises from a declaration that redefines the same identifier within the 
program. 

NOTTH 

Standard procedures and functions cannot be used as actual procedural 
and functional parameters. 

This chapter uses a modified BNF notation, instead of syntax diagrams, to 
indicate the syntax of actual-parameter- lists for standard procedures and 
functions. The notation is explained at the beginning of Chapter 10. 

11.1 Exit and Halt Procedures 

11.1.1 The Exit Procedure 

Exits immediately from a specified procedure or function, or from the main 
program. 

Parameter List' exit (id) 

1. id is the identifier of a procedure or function, or of the main program. If 
id is an identifier defined in the program, it must be in the scope of the 
exit call. Note that this is more restricted than UCSD Pascal. 

Exit(id) causes an immediate exit from id. Essentially, it causes a jump to the 
end of id. 

NOTE 

The halt procedure (see below) can be used to exit the main program 
from a unit without knowing the main program's identifier. 

11.1.2 The Halt Procedure 

Exits immediately from the main program. 

Parameter List- no parameters 

Halt causes an immediate exit from the main program. 

11.2 Dynamic Allocation Procedures 

These procedures are used to manage the heep, a mennory area that is 
unallocated when the program starts running. The procedure new is used for 
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all allocation of heap space by the program. The mark and release procedures 
are used together to deallocate heap space, and the heapresult function is used 
to return the status of the last preceding dynamic allocation operation.. 

11.Z1 The New Procedure 

Allocates a new dynamic variable and sets a pointer variable to point to it 

ParametBr Ust- nei»(p \, tl^ ... t/?]) 

1. p is a variable-reference that refers to a variable of any pointer-type. 
This is a variable parameter. 

2. 11, ... t/7are constants, used only when allocating a variable of 
record-type with variants (see below). 

New(p) allocates a new variable of the base-type of p, and makes p point to It. 
The variable can be referenced as p". Successive calls to new allocate 
contiguous areas. 

If the heap does not contain enough free space to allocate the new variable, p 
is set to nil and a subsequent call to the heapresult function will return a 
non-zero result 

If the base-type of p is a record-type with variants, new(p) allocates enough 
space to allow for the largest variant. The form 

new(p, tl, ...t/7) 

allocates a variable with space for the variants specified by the tag values tl, 
... t/7 (instead of enough space for the largest variants). The tag values must 
be constants. They must be listed contiguously and In the order of their 
declaration. The tag values are not assigned to the tag-fields by this 
procedure. 

Trailing tag values can be omitted. The space allocated allows for the largest 
variants for all tag-values that are not specified. 

WARNING 

When a record variable is dynamically allocated with e>qDlicIt tag values 
as shown above, you should not make assignments to any fields of 
variants that are not selected by the tag values. Also, you should not 
assign an entire record to this record. If you do either of these things, 
other data can be overwritten without any error being detected at 
conpile time. 
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11J2^ The Heapresult Function 

Returns the status of the most recent dynamic allocation operation. 

Result Type: integer 

Parameter List- no parameters 

Heapresult returns an integer code that reflects the status of the most recent 
call on new, mark, release, or memavail. The codes are given in the Workshop 
User's Guicfe; note that the code for a successful operation is 0. 

11J2.3 The Mark Procedure 

Sets a pointer to a heap area. 

Parameter List- inark(p) 

1. p is a variable-reference that refers to a variable of any pointer-type. 
This is a variable parameter. 

Mai1<(p) causes the pointer p to point to the lowest free area in the heap. The 
next call to new will allocate space beginning at the bottom of this area, and 
then p will be a pointer to this space. The pointer p is also placed on a 
stack-like list for subsequent use with the release procedure (see below). 

11.2.4 The Release Procedure 

Deallocates all variables in a marked heap area. 

Parameter List release(p) 

1. p is a variable-reference that refers to a pointer variable. It must be a 
pointer that was previously set with the mark procedure. The pointer p 
must be on the list created by the mark procedure; otherwise an error 
occurs. 

Release(p) removes pointers from the list, back to and including the pointer p. 
The heap areas pointed to by these pointers are deallocated. In other words, 
release(p) deallocates all areas allocated since the the pointer p was passed to 
the mark procedure. 

1L23 The Memavail Function 

Returns the maximum possible amount of available memory. 

Result Type: longint 

Parameter List' no parameters 

Memavail returns the maximum number of words (not bytes) of heap and stack 
space that could ever be available to the program, allowing for possible 
automatic expansion of the program's data segment Note that the result of 
memavail can change over time even If the program does not allocate any 
heap space, because of activities by the operating system or other processes in 
the system. 
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113 Transfer Functions 

The procedures pack and uipack, described by Jensen and Wirth^ are not 
supported. 

11.3.1 The Trunc Function 

Converts a real value to a longint value. 

Result Type: longint 

Parameter List: trunc(x) 

1. X is an expression with a value of type real. 

Tnjnc(x) returns a longint result that is the value of x rounded to the largest 
whole number that is between and x (inclusive). 

113.2 "me Round Function 

Converts a real value to a longint value. 

Result Type: longint 

Parameter List- round(x) 

1. X is an expression with a value of type real. 

Round(x) returns a longint result that is the value of x rounded to the nearest 
whole number. If x is exactly halfway between two whole numbers, the result 
is the whole number with the greatest absolute magnitude. 

1133 The Qrd4 FuncUon 

Converts an ordinal-type or pointer-type value to type longint 

Result Type: longint 

Parameter List- ord4(x) 

1. X is an expression with a value of ordinal-type or pointer-type. 

Qn*i(x) returns the value of X/ converted to type longint If x is of type 
longint the result is the same as x. 

If X is of pointer-type, the result is the corresponding physical address, of type 
longint 

If X is of type integer, the result is the same numerical value represented by x, 
but of type longint This is useful in arithmetic expressions. For example, 
consider the expression 

abc*xyz 

where both abc and xyz are of type integer. By the rules given in Section 
3.1.1.2, the result of this multiplication is of type integer (16 bits). If the 
mathematical product of abc and xyz cannot be represented in 16 bits, the 
result is the low-order 16 bits. To avoid this, the expression can be written as 

ord4(abc)*xyz 
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This expression causes 32-bit arithmetic to be used, and the result is a 32-blt 
longint value. 

If X is of an ordinal-type other than integer or longint the numerical value of 
the result is the ordinal number determined by mapping the values of the type 
onto consecutive non-negative integers starting at zero. 

113.4 The Pointer Function 

Converts an integer or longint value to pointer-type. 

Result Type: pointer 

Parameter List: pointer(x) 

1. X is an expression with a value of type integer or lorjigint 

Pointei(x) returns a pointer value that corresponds to the physical address x. 
This pointer is of the same type as nil and is assignment-compatible with any 
pointer-type. 

11-4 Arithmetic Functions 

In general, any real result returned by an arithmetic function is an approx- 
imation. There are two exceptions to this: the result of the abs function is 
exact, and the result of the pwroften function is exact when the parameter n 
is in the range < n < 10. 

11.4.1 TTie Odd FuncUon 

Tests whether a whole-number value is odd. 

Result Type: boolean 
Parameter List: odd(x) 

1. X is an expression with a value of type integer or longint 
Odd(x) returns true if x is odd; otherwise it yields false. 

11.4.2 Trie Abs Function 

Returns the absolute value of a numeric value. 

Result Type: same as parameter 
Parameter List: abs(x) 

1. X is an expression with a value of type real, integer, or longint 
Abs(x) returns the absolute value of x. 
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1L43 The Scpr Function 

Returns the square of a numeric value. 

Result Type: depends on parameter (see below) 

Parameter List- sqr(x) 

1. X is an expression with a value of type real^ integer, or longint 

Sqi(x) returns the square of x If x is of type real, the result is real; if x is of 
type longint the result is longint; and if x is of type integer, the result may be 
either integer or longint 

If X is of type real and floating-point overflow occurs, the result is +«>. 

11A4 The Sin Function 

Returns the sine of a numeric value. 

Result Type: real 

Parameter List- sin(x) 

1. x is an expression with a value of type real, integer, or longint This 
value is assumed to represent an angle in radians. 

Sir(x) returns the sine of x If x is infinite, a diagnostic NaN is produced and 
the invalid operation signal is set (see Appendix D\ 

1L4.5 The Cos Function 

Returns the cosine of a numeric value. 

Result Type: real 

Parameter List: cos(x) 

1. X is an expression with a value of type real, integer, or longint This 
value is assumed to represent an angle in radians. 

Cos(x) returns the cosine of x If x is infinite, a diagnostic NaN is produced 
and the Invalid operation signal is set (see Appendix D). 

11A6 The Exp FuncUon 

Returns the exponential of a numeric value. 

Result Type: real 

Par&r^ter List' exp(x) 

1. X Is an expression with a value of type real, integer, or longint All 
possible values are valid. 

Ex|](x) returns the value of e ^, where e is the base of the natural logarithms. 
If floating-point overflow occurs, the result is +«». 



11-6 



Pascal Reference Manual Standard Procedures & Functions 

11A7 TTie Ln Function 

Returns the natural logarithm of a numeric value. 

Result Type: real 

Parameter List- ln(x) 

1. X is an expression with a value of type real^ integer^ or longint All 
non-negative values are valid; negative values are invalid. 

If X is non-negative, ln(x) returns the natural logarithm (log^ ) of x 

If X is negative, a diagnostic NaN is produced and the Invalid Operation signal 
is set (see Appendix D). 

11.4.8 The Sqrt Function 

Returns the square root of a numeric value. 

Result Type: real 

Parameter List' sc|rt(x) 

1. X is an expression with a value of type real, integer, or longint All 
non-negative values are valid; negative values are invalid. 

If X is non-negative, sc|rt(x) returns the positive square root of x 

If X is negative, a diagnostic NaN is produced and the Invalid Operation signal 
is set (see Appendix D). 

11.4w9 The Arctan Function 

Returns the arctangent of a numeric value. 

Result Type: real 

Parameter List: arctan(x) 

1. X is an expression with a value of type real, integer, or longint All 
numeric values are valid, including ±«». 

Arctan(x) returns the principal value, in radians, of the arctangent of x 

11.4.10 The Pwroften Function 

Returns a specified power of 10. 

Result Type: real 
Parameter List- pwroftenCn) 
1. n is an expression with a value of type integer. 

If -45 < n < 38, then pwroften(n) returns lo". The result is mathematically 
exact f or < n < ID. If n < -46, the result is 0; if n > 39, the result is +«». 
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113 Ordinal Functions 
115.1 The Qrd Function 

Returns the ordinal number of an ordinal-type or pointer-type value. 

Result Type: Integer or longint 

Parwneter List' ord(x) 

1. X is an expression with a value of ordinal-type or pointer-type. 

If X is of type integer or longint the result is the same as x 

If X is of pointer-type, the result is the corresponding physical address, of type 
longint 

If X is of another ordinal-type, the result is the ordinal number determined by 
mapping the values of the type onto consecutive non-negative whole numbers 
starting at zero. 

For a parameter of type char, the result Is the corresponding ASCII code. For 
a parameter of type twolean, 

ord(false) returns 
ord(true) returns 1 

11.5.2 ine Chr Function 

Returns the char value corresponding to a whole-number value. 

Result Type: char (but see below) 

Parameter List- chr(x) 

1. X is an expression with an integer or longint value. 

Chi(x) returns the char value whose ordinal number (i.e., its ASCII code) is x, if 
X is in the range 0-255. If x is not in the range D..255, the value returned is 
not within the range of the type char, and any attempt to assign it to a 
variable of type char will cause an error. 

For any char value ch, the following is true: 

chr(ord(ch)) = ch 

11.5.3 The Succ Function 

Returns the successor of a value of ordinal- type. 

Result Type: same as parameter (but see below) 

Parameter UsL' succ(x) 

1. X is an expression with a value of ordinal-type. 

Succ(x) returns the successor of x, if such a value exists according to the 
inherent ordering of values in the type of x 



11-8 



Pascal Reference Manual Standard Procedures & Functions 

If X is the last value in the type of x, it has no successor. In this case the 
value returned is not within the range of the type of x. and any attempt to 
assign it to a variable of this type will cause unspecified results. 

11S.4 The Pred Function 

Returns the predecessor of a value of ordinal-type. 

Result Type: same as parameter (but see below) 

Parameter List: pred(x) 

1. X is an expression with a value of ordinal-type. 

Pred[x) returns the predecessor of x, if such a value exists according to the 
inherent ordering of values in the type of x 

If X is the first value in the type of x, it has no predecessor. In this case the 
value returned is not within the range of the type of x, and any attempt to 
assign it to a variable of this type will cause unspecified results. 

11.6 String Pnx»dures and Functions 

The string procedures and functions do not accept packed array of char 
parameters, and they do not accept indexed string parameters. 

11.6.1 The Length Function 

Returns the current length of a value of string-type. 

Re^lt Type: integer 
Parameter List: length(str) 

1. str is an expression with a value of string-type. 
Length(str) returns the current length of str. 

11-6.2 TTie Pos Function 

Searches a string for the first occurrence of a specified substring. 

Result Type: Integer 

Parameter List- pos(substr^ str) 

1. sutotr is an expression with a value of string-type. 

2. str is an expression with a value of string-type. 

Pos(substr^ str) searches for substr within str, and returns an integer value that 
is the index of the first character of substr within str. 

If substr Is not found, pos(substr, str) returns zero. 
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11£3 TTk CancaX Function 

Takes a sequence of strings and concatenates them. 

Result Type: string-type 

Parameter Ust- concat(strl {, str2, ... str/?]) 

• Each parameter is an expression with a value of string-type. Any practical 
numlDer of parameters may be passed. 

Concat(strl, -^ str/?) concatenates all the parameters in the order in which 
they are written, and returns the concatenated string. Note that the number 
of characters in the result cannot exceed 255. 

11.6.4 TTie Copy Function 

Returns a substring of specified length, taken from a specified position within 
a string. 

Result T)pe: string-type 

Parameter List- copy(source, inde^, count) 

1. source is an expression with a value of string-type. 

2. index is an expression with an integer value. 

3. count is an expression with an integer value. 

Copy(source, inde)c count) returns a string containing count characters from 
source, beginning at source[index]. 

11.63 The Delete Procedure 

Deletes a substring of specified length from a specified position within the 
value of a string variable. 

Parmwter Ust: delete(dest, inde\, count) 

1. dest is a variable-reference that refers to a variable of string-type. This 
is a variable parameter. 

2. index is an expression with an integer value. 

3. count is an expression with an integer value. 

Delete(dest inde)c count) removes count characters from the value of dest, 
beginning at dest[index} 

11.6.6 The Insert Procedure 

Inserts a substring into the value of a string variable, at a specified position. 

Parameter List- insert (source, dest, index) 

1. source is an expression with a value of string-type. 

2. dest is a variable-reference that refers to a variable of string- type. This 
is a variable parameter. 

3. index is an expression with an integer value. 
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Insert(source, dest, index) inserts source into dest Tne first character of 
source becomes destfindexj 

11.7 Byte-Qriented Procedures and Functions 

These features allow a program to treat a program variable as a sequence of 
bytes, without regard to data types. 

NOTE 

The sizeof function (described in Section 11.7.3, below) can be used to 
determine the number of bytes in a variable. 

These procedures do no type-checking on their source or dest actual- 
parameters. However, since these are variable parameters they camot be 
Indexed if they are packed or if they are of string-type. If an unpacked 
"byte array" is desired, then a variable of the type 

array [lo..hl] of -128.. 127 

should be used for source or dest The elements in an array of this type are 
stored in contiguous bytes, and, since it is unpacked, an array of this type can 
be used with an index as an actual-parameter for these routines. 

IMPLEMENTATION NOTE 

Currently, an array with elements of the type a.255 or the type char 
has its elements stored in words, not bytes. 

11.7.1 The Movelefl Procedure 

Copies a specified number of contiguous bytes from a sajrce rang^ to a 
destlnatim ran^ (starting at the lowest address). 

Par&neter List' inoveleft( source, dest, count) 

1. source is a variable-reference that refers to a variable of any type 
except a file-type or a structured-type that contains a file-type. This is 
a variable parameter. The first byte allocated to source (lowest address 
within source) is the fint byte of the source range. 

2. dest is a variable-reference that refers to a variable of any type except 
a file-type or a structured- type that contains a file-type. This is a 
variable parameter. The first byte allocated to dest (lowest address 
within dest) is the first byte of the destination range. 

3. count is an expression with an integer value. The source range and the 
destination range are each count bytes long. 

Moveleft(source,. dest, count) copies count bytes from the source range to the 
destination range. 
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Moveleft starts from tne "left" end of the source range (lowest address). It 
proceeds to the "right" (higher addresses), copying bytes into the destination 
range, starting at the lowest address of the destination range. 

The count paranneter is not range-checked. 

11.7.2 The Moveright Pnxjedure 

Moveright is exactly like moveleft (see above), except that it starts from the 
"right" end of the source range (highest address). It proceeds to the "left" 
(lower addresses), copying bytes into the destination range, starting at the 
highest address of the destination range. 

The reason for having both moveleft and moveright is that the source and 
destination ranges may overlap. If they overlap, the order in which bytes are 
moved is critical: each byte must be moved before it gets overwritten by 
another byte. 

11.7.3 The Slzeof FuncUon 

Returns the number of bytes occupied by a specified variable, or by any 
variable of a specified type. 

Result Type: integer 

Parameter List: sizeof(id) 

1. Id is either a variable-identifier or a type-identifier. It must not refer to 
a file-type or a structured-type that contains a file-type, or to a 
variable of such a type. 

Sizeof(ld) returns the number of bytes occupied by id, if id is a variable- 
identifier; if id is a type-identifier, it returns the number of bytes occupied by 
any variable of type Id. 

11.8 Packed Array of Char Procedures and Functions 

NOTE 

These routines operate only on packed arrays of char. The packed 
arrays of char cannot be subscripted; the operations always begin at the 
first character in a packed array of char. 

11.8.1 TTie Scaneq Function 

Searches a packed array of char for the first occurrence of a specified 
character. 

Result T}pe: Integer 

Parameter List: scaneq( limit, ch, paoc) 

1. limit is an expression with a value of type integer or longint It is 
truncated to 16 bits, and is not range-checked. 

2. ch is an expression with a value of type c*iar. 
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3. paoc is an expression with a value of type packed array of char. This is 
a variable parameter. 

Scaneq(limlt, ch, paoc) scans paoc^ looking for the first occunence of ch. The 
scan begins with the first character in paoc. If the character is not found 
within limit characters from the beginning of paoc, the value returned is equal 
to limit Otherwise, the value returned is the number of characters scanned 
before ch was found. 

1L8J2 The Scanne Function 

This function is exactly like scaneq, except that it searches for a character 
that does not match the ch parameter. 

lLa3 The Fillchar Procedure 

Fills a specified number of characters in a packed array of char with a 
specified character. 

Parmteter List- fillchar(paoc, count, ch) 

1. paoc is an expression with a value of type packed array of char. This is 
a variable parameter. 

2. count is an expression with a value of type Integer or longlnt It is 
truncated to 16 bits, and is not range-checked. 

3. ch is an expression with a value of type char. 

Flllchai(paoc, count, ch) writes the value of ch into count contiguous bytes of 
memory, starting at the first byte of paoc. 

Since the count parameter is not range-checked, it is possible to write into 
memory outside of paoc, with unspecified results. 
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The Compiler 



The Pascal compiler translates Pascal source text to an Intermediate code, and 
the code generator translates the Intermediate code to MC68000 object code. 
Instructions for operating the compiler and code generator are given in the 
Workshop User's Guide for the Lisa 

12.1 Compiler Commands 

A compiler command is a text construction, embedded in source text, that 
controls compiler operation. Every compiler command is written within 
comment delimiters, {...} or (*...*)i Every compiler command begins with the $ 
Character, which must be the first character inside the comment delimiters. 

In this manual, compiler commands are shown in upper case to help distinguish 
them from Pascal program text; however, upper and lower case are inter- 
changeable in compiler commands just as they are in Pascal program text. 

The following compiler commands are available: 

INPUT FILE CONTROL 

$1 filename start taking source code from file filename. When the end 
of this file is reached, revert to the previous source file. 
If the filename begins with + or -, there must be a space 
between $1 and the filename (the space is not necessary 
otherwise). 

$U filename Search the file filename for any units subsequently 

specified in the uses-clause. Does not apply to intrinsic- 
units. 

CONTROL OF CODE GENERATION 

$C+ or $C- Turn code generation on (+) or off (-). This is done on a 
procedure-by-procedure basis. These commands should be 
written between procedures; results are unspecified if they 
are written inside procedures. The default is $C+. 

$0V+ or $0V- Turn integer overflow checking on (♦) or off (-). Overflow 
checking is done after all integer add, subtract, 16-blt 
multiply, divide, negate, abs, and 16-bit square operations, 
and after 32 to 16 bit conversions. The default is $GV-. 

$R+ or $R- Turn range checking on (♦) or off (-). At present, range 
checking is done in assignment statements and anay 
indexes and for string value parameters. No range 
checking is done for type longint The default is $R+. 
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$S segname start putting code nrxxlules Into segment segname. The 

default segment name is a string of blanks to designate the 
"blank segment," In which the main program and all built-in 
support code are always linked. All other code can be 
placed into any segnnent. 

$X+ or $X- Turn automatic run- time stack expansion on (+) or off (-> 
The default Is $X+. 

NOTE 

Compiler directives that affect code generation take effect when the 
end of the Pascal statement in which they are embedded is reached. If 
the same directive is specified more than once in a statement, the last 
setting is used. A tricky case of this is: 

begin 
j := foo; 
{$R-} 

i := i»2 

end 

Since the second assignment does not end with a semicolon, and 
actually ends when the end is encountered, range checking will not be 
turned off for that statement. 



DEBLJGGING 

$0* or $D- Turn the generation of procedure names in object code on 
{+) or off (-). These commands should be written between 
procedures; results are unspecified if they are written 
inside procedures. The default is $D+. 

CCNDITIONAL COMPILATION 

$OECL list (see Section 12.2 below), 

$ELSEC (see Section 12.2 below). 

$ENDC (see Section 12.2 below). 

$IFC (see Section 12.2 belowX 

$SETC (see Section 12.2 below). 
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LISTING CONTROL 

$E filename Start making a listing of compiler errors as they are 

encountered. Analogous to $L filename (see below). The 
default is no error listing, 

$L filename Start listing the compilation on file filename, if a listing 
is being made already, that file is closed and saved prior to 
opening the new file. The default is no listing. If the 
filename begins with ♦ or -, there must be a space between 
$L and the filename (the space is not necessary otherwise). 

SL* or $L- The first ♦or - following the $L turns the source listing on 
(♦) or off (-) without changing the list file. You must 
specify the listing file before using $L+. The default Is 
$L+, but no listing Is produced If no listing file has been 
specified, 

12.2 Conditional Compilation 

Conditional compilation is controlled by the $IFC, $ELSEC, and $ENDC 
commands, which are used to bracket sections of source text. Whether a 
particular bracketed section of a program Is complied depends on the boolean 
value of a complle-tlme expression which can contain compUe-tlme variables 

12.2.1 Complle-Tlme variables and the $CECL Command 

Complle-tlme variables are completely Independent of program variables; even 
If a complle-tlme variable and a program variable have the same Identifier, 
they can never be confused by the compiler. 

A complle-tlme variable Is declared when It appears In the Identlfler-llst of a 
$DECL command. 

Exanple of complle-tlme variable declaration: 

{$OeCL LIBVERSION. PROGVERSION} 

This declares LIBVERSION and PROGVERSION as complle-tlme variables. 
Notice that no types are specified. 

Note the following points about complle-tlme variables: 

• Complle-tlme variables have no types, although their values do. The only 
possible types are integer and boolean. 

• All complle-tlme variables should be declared before the end of the 
varlable-declaratlon-part of the main program. In other words a $DECL 
command that declares a new complle-tlme variable must precede the 
main program's procedure and function declarations (If any). The new 
complle-tlme variable Is then known throughout the remainder of the 
compilation. 

• At any point In the program, a complle-tlme variable can have a new 
value assigned to It by a $SETC command. 
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12.2^ Tne $SETC command 

The $SETC command has the form 

{$SETC ID := EXPR} 

{$SETC ID = EXPR} 

where ID is the identifier of a compile-time variable and EXPR is a complle- 
tlme expression. EXPR Is evaluated Immediately. The value of EXPR Is 
assigned to ID. 

Example of assignment to compUe-tlme varlattle: 

{$SETC LIBVERSION := 5} 

This assigns the value 5 to the compile-time variable LIBVERSION. 

12.23 Complle-Time Expressions 

complie-tlme expressions appear In the $SETC command and In the $IFC 
command. A compile-time expression is evaluated by the compiler as soon as 
It Is encountered In the text 

The only operands allowed in a compile-time expression are: 

• Compile-time variables 

• Constants of the types Integer and booleaa (These are also the only 
possible types for results of compile-time expressions.) 

All Pascal operators are allowed except as follows: 

• The in operator is not allowed. 

• The 9 operator is not allowed. 

• The / operator is automatically replaced by div. 

12.2.4 The $IFC^ «ELSEC. and $ENDC Commands 

The SELSEC and SENDC commands take no arguments. The $IFC command has 
the form 

{$IFC EXPR} 

Where EXPR is a complle-tlme expression with a boolean value. 

These three commands form constructions similar to the Pascal if-statemenc 
except that the $ENDC command is always needed at the end of the $IFC 
construction. $ELSEC is optional. 
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Example of concfJUonalJy compJlecf code: 

{$IFC PROGVERSION >= LIBVERSION} 

k := kvall(data+indat); 
{$ELSEC} 

k := kval2(data+cplndat " ); 
{$ENDC} 

•rlteln(k) 

If the value of PROGVERSION is greater than or equal to the value of 
LIBVERSION^ then the statement k:-kvall(data+incial) is compiled^ and the 
statement kr-kvalZCdata+opindal") is skipped. 

But if the value of PROGVERSION is less than the value of LIBVERSION, then 
the first statement is skipped and the second statement is compiled. 

In either case, the wrlteinCk) statement is compiled Decause the conditional 
construction ends with the $ENDC command. 

$IFC constructions can Pe nested within each other to 10 levels. Every $IFC 
must have a matching SENDC. 

When the compiler is skipping, all commands in the skipped text are ignored 
except the following: 

$ELSEC 

SENDC 

$IFC (so that $ENDC's can be matched properly) 

All program text is ignored during skipping. If a listing is produced, each 
source line that is skipped is marked with the letter S as its "lex level." 

12.3 Optimization of If-Statements 

When the compiler finds an if-statement controlled by a boolean constant, it 
may be unnecessary to compile the then part or the else part. For example, 
given the declarations 

const always = true; 
never = false; 

then the statement 

If never then statement 

will not be compiled at all. In the statement 

if never then statementl 
else statementz 

"statementl" is not compiled; only "statement2" is compiled. 
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Similarly^ in the statement 

if always then statementl 
else statement? 

only "statementl" Is compiled. 

The interaction between this optimization and conditional compilation can be 
seen from the following program: 

prograro Foo; 

{$SETC FLAG := FALSE} 

const pi = 3.1415926; 

Size = 512; 
{$IFC FLAG} 

debug = false; (a txwlean constant, if FLAG=true} 
{$ENDC} 

var i^j^k^l^tiun: integer; 
{$IFC NOT FLAG} 

debug: boolean; (a boolean variable, if FLAG=false} 
{$ENDC} 

{$IFC NOT FLAG} 
procedure imatinode; 

begin 
{interactive procedure to set global boolean variable, debug} 

end; 
{$ENDC} 

begin {main} 
{$IFC NOT FLAG} 

whatinode; 
{$ENDC} 

if debug then begin 

statementl 
end 
else begin 

statement? 
end 

end. 

The way this is compiled depends on the compile-tlme variable FL/>G. If 
FLAG is false, then debug is a boolean variable and the whatmode procedure 
is conpiled and called at the beginning of the main program. The if debug 
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statement is controlled by a txx)lean variable and all of it is compiled, in the 
usual manner. 

But if the value of FLAG is changed to tme^ then debug is a constant with 
the value false, and wtiatmcxJe is neither compiled nor called. The if debug 
statement is controlled by a constant, so only its else part, "statementZ", is 
compiled. 

12.4 Optimization of While-Statements and Repeat-Statements 

A While-Statement or repeat-statement controlled by a boolean constant does 
not generate any conditional branches. 

12.5 Efficiency of Case-Statements 

A sparse or small case-statement will generate smaller and faster code than 
the corresponding sequence of if-statements. 
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Comparison to Apple 11 
and Apple III Pascal 



This appendix contains lists of the major differences between the Pascal 
language on the Lisa and the Pascal implemented on the Apple II and Apple 
III. Please note that these lists are not exhaustive. 

A.l Extensions 

The following features have been added on the Lisa.- 

■ 3 Operator—returns the pointer to its operand (see Section 5.1.6). 

■ Heapresult, pointer^ and ord4 functions fsee Sections 11.2.2, 11.3.3, and 
11.3.4). 

» Keypress function built into the language, with same effect as the 
keypress function in the applestuff unit of Apple II and Apple III Pascal 
(see Section 10.3.7.1). 

■ Hexadecimal constants (see Section 1.4). 

- Otherwise-clause in case-statement (same as Apple III Pascal; see 
Section 6.2.2.2). 

■ Global goto-statement (see Section 6.1.3). 

- A file of char type that is distinct from the text type (see Sections: 
3.2.4 and 10.3). 

« Numerous compiler commands (see Section 12.1). 

■ Procedural and functional parameters (see Sections 7.3.3 and 7.3.4). 

■ Stronger type-checking (see Sections 3.4 and 7.3.5). 

A.2 Deletions 

The following features are not included on the Lisa: 

■ Turtle^aphics, applestuff, and other standard units of Apple II and 
Apple III Pascal. 

- Interactive type (not needed, as the I/O procedures will do the right 
thing with a file of type text if it is opened on a character de\/ice). 

■ Keyboard file — same effect can be obtained by opening a file of type 
text on the device -KEYBOARD (see Section 10.3). 

■ Unit (device-oriented) I/O procedures. 
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Cornpenscn to f^pple II & III Pascal 



Recognition of the ETX chai-acter (control-C) to mean "end of file" in 
input from a character device. 

"Long integer" data type, with length attribute in declaration. Replaced 
by the longimt type (see Section 3.1.1.2). 

"Initialization" code in a unit (see Section 9). 

The ability to create new intrinsic-units and install them in the system 
(see Section 9). 

Reset procedure without an external file title, for use on a file that is 
already open (see Section 10.1.1). To obtain the same effect, close the 
file and reopen it. 

Treesearch. 

Bytestream, wordstxeam (data types in Apple III Pascal). 

Exit(parogram) — The exit(identifier) form works, and the identifier can be 
the program-identifier. Halt can also be used for orderly exit from a 
progi-am (see Section 11.1). 

Extended comparisons (see Section 5.1.5). 

Scan function. Replaced by scaneq and sccrwie (see Section 11.8). 

Bit-v/ise boolean operations. 

Segment keyword for procedures and functions. Use the $S command 
instead (see Section 12.1). 

The following compiler commands (see Section 12.1).- 

- $1+ and $1- (no automatic I/O checking; programi must use ioresult 
function). 

■ $G ($G+ is the assumption on the Lisa). 

- $N and $R (for resident code segments). 
-$Q- 

■ $S+ and $S++ for swapping. 

■ $U+ and $U- (for User Program). 

-$V. 

In general, do not assume that a compiler command used in Apple II or 
Apple III Pascal is valid on the Lisa. Furthermore, do not assume that an 
Apple II or Apple III Pascal compiler command is "harmless" on the Lisa, as 
it may be implemented with a different meaning. 
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A.3 Other Differences 

The following features of Pascal on the Lisa are different from the 
coiTesponding features of Apple II and Apple III Pascal: 

- Size of all strings must be explicitly declared (see Section 3.1.1.6). 

- Mod and div— Pascal on the Lisa truncates toward (see Section 5.1.2). 

■ Apple II and Apple III Pascal ignore underscores; Pascal on the Lisa 
does not. They are legal characters in identifiers (see Section 1.2). 

■ A goto-statement cannot refer to a case-constant in Pascal on the Lisa 
(see Section 6.1.3). 

■ A program must begin with the word program in Pascal on the Lisa (see 
Chapter 8). 

■ Trunc is different (see Section 11.3.1). 

- Write(b) where b is a boolean will write either ' TRUE' or 'FALSE' in 
Pascal on the Lisa (see Section 10.3.3). 

■ Whether a file is a textf ile does not depend on whether its name ends 
with ".TEXT" when it is created. Instead, any external file opened with 
a file variable of type text is treated as a textfile, while a file opened 
with a file variable of type file of thm is not; it is treated as a 
"dataf ile," i.e. a straight file of records which are of type char (see 
Sections 3.2.4 and 10.2). 

■ Get, put, and the contents of the file buffer variable are not supported 
on files of type text. Use only the text-oriented I/O procedures with 
textfiles. 

■ Eoln and eof functions on files of type text work as the-y do on 
interactive files in Apple II and Apple III Pascal. 

■ Pascal on the Lisa does not let you pass an element of a packed 
variable as a vaiiable parameter (see Sections 7.3.2, 11.7, and 11.8). 

- Limits on sets are different (see Section 3.2-3). 

■ The control variable of a for-statement must be a local variable (see 
Section 6.2.3.3). 

■ In a write or writeln call, the default field lengths for integer and real 
values are 8 and 12 respectively (see Section 10.3.3). 

A.4 Predefined Identifiers 

The predefined identifiers listed in Table A-1 are built into the Pascal 
Compiler for each machine, as indicated. If you declare or define these 
names in your program, no Compiler error will result, but you will lose the 
capacity of the corresponding built-in, or predefined, entity. The list does 
not include identifiers in special library units, such as those in the 
QuickDraw graphics unit. 
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Table f\-l 

F^edefined Iftentifiers 
in the Lisa Pascal Compiler 



Identifier 


Type 


Lisa 


ADDle /// 


ADDle 1 r 


ABS 


Generic function 


Yes 


Yes 


Yes 


BLOCKREAD 


Integer function 


Yes 


Yes 


Yes 


BLOCKWRITE 


Integer function 


Yes 


Yes 


Yes 


BOOLEAN 


Type 


Yes 


Yes 


Yes 


BYTESTREAM 


Type 


No 


Yes 


No 


CHAR 


Type 


Yes 


Yes 


Yes 


CHR 


Character function 


Yes 


Yes 


Yes 


CLOSE 


Procedure 


Yes 


Yes 


Yes 


CONCAT 


String function 


Yes 


Yes 


Yes 


COPY 


String function 


Yes 


Yes 


Yes 


DELETE 


Procedure 


Yes 


Yes 


Yes 


EOF 


Boolean function 


Yes 


Yes 


Yes 


EOLN 


Boolean function 


Yes 


Yes 


Yes 


EXIT 


Procedure 


Different 


Yes 


Yes 


EXP 


Real function 


Yes 


Yes 


Yes 


FALSE 


Constant 


Yes 


Yes 


Yes 


FILLCHAR 


Procedure 


Different 


Yes 


Yes 


GET 


Procedure 


Yes 


Yes 


Yes 


GOTOXY 


Procedure 


Yes 


Yes 


Yes 


HALT 


Procedure 


Yes 


Yes 


Yes 


HEAPRESULT 


Integer function 


Yes 


No 


No 


IDSEARCH 


Procedure 


No 


Yes 


Yes 


INCLASS 


Boolean function 


Yes 


No 


No 


INPUT 


File 


Yes 


Yes 


Yes 


INSERT 


Procedure 


Yes 


Yes 


Yes 


INTEGER 


Type 


Yes 


Yes 


Yes 


INTERACTIVE 


Type 


Yes 


Yes 


Yes 
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Identifier 


Tvpe 


Lisa 


Apple /// 


Apple ir 


lORESULT 


Integer function 


Yes 


Yes 


Yes 


KEYBOARD 


File 


Device 


Yes 


Yes 


KEYPRESS 


Boolean function 


In library 


Yes 


Yes 


LENGTH 


Integer function 


Yes 


Yes 


Yes 


LN 


Real function 


Yes 


Yes 


Yes 


LOG 


Real function 


No 


Yes 


Yes 


LONGINT 


Type 


Yes 


No 


No 


MARK 


Procedure 


Different 


Yes 


Yes 


MAXINT 


Constant 


Yes 


Yes 


Yes 


MEMAVAIL 


Integer function 


Different 


Yes 


Yes 


MOVELEFT 


Procedure 


Different 


Yes 


Yes 


MOVERIGHT 


Procedure 


Different 


Yes 


Yes 


NEW 


Procedure 


Different 


Yes 


Yes 


ODD 


Boolean function 


Yes 


Yes 


Yes 


ORD 


Integer function 


Yes 


Yes 


Yes 


0RD4 


Integer function 


Yes 


No 


No 


OUTPUT 


File 


Yes 


Yes 


Yes 


PAGE 


Procedure 


Yes 


Yes 


Yes 


POINTER 


Pointer function 


Yes 


No 


No 


POS 


Integer function 


Yes 


Yes 


Yes 


PRED 


Integer function 


Yes 


Yes 


Yes 


PUT 


Procedure 


Yes 


Yes 


Yes 


PWROFTEN 


Real function 


Yes 


Yes 


Yes 


READ 


Ftocedure 


Yes 


Yes 


Yes 


READLN 


Procedure 


Yes 


Yes 


Yes 


REAL 


Type 


Yes 


Yes: 


Yes 


RELEASE 


Procedure 


Different 


Yes 


Yes 


RESET 


Procedure 


Different 


Yes 


Yes 


REWRITE 


Procedure 


Yes 


Yes 


Yes 


ROUND 


Integer function 


Yes 


Yes 


Yes 
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Identifier 


Tvpe 


i.is»i 


ADDle /// 


ADDle 1 r 


SCAN 


Integer function 


No 


Yes 


Yes 


SCANEQ 


Integer function 


Yes 


No 


No 


SCANNE 


Integer function 


Yes 


No 


No 


SEEK 


Procedure 


Yes 


Yes 


Yes 


SIZEOF 


Integer function 


Yes 


Yes 


Yes 


SQR 


Generic function 


Yes 


Yes 


Yes 


SQRT 


Real function 


Yes 


Yes 


Yes 


STR 


String function 


No 


Yes 


Yes 


STRING 


Type function 


Length req 


Yes 


Yes 


SUCC 


Integer function 


Yes 


Yes 


Yes 


TEXT 


Type function 


Different 


Yes 


Yes 


THISCLASS 


Pointer function 


Yes 


No 


No 


TREESEARCH 


Integer function 


No 


Yes 


Yes 


TRUE 


Constant 


Yes 


Yes 


Yes 


TRUNC 


Integer function 


Yes 


Yes 


Yes 


UNITBUSY 


Boolean function 


No 


Yes 


Yes 


UNITCLEAR 


Procedure 


No 


Yes 


Yes 


UNITREAD 


Procedure 


No 


Yes 


Yes 


UNITSTATUS 


Procedure 


No 


Yes 


No 


UNIT WAIT 


Procedure 


No 


Yes 


Yes 


UNITWRITE 


Procedure 


No 


Yes 


Yes 


WORDSTREAM 


Type 


No 


Yes: 


No 


WRITE 


Procedure 


Yes 


Yes 


Yes 


WRITELN 


Procedure 


Yes 


Yes 


Yes 
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This appendix describes tte known anomalies in the current implementation of 
the compiler. 

B.1 Scope of Declared Ooratants 

Consider the following program: 

program csccpel; 
const ten=10; 

procedure p; 
const ten=ten; {WIS SHOULD BE AN ERROR} 
begin 

OTiteln(ten) 
end; 

begin 

P 
end. 

The constant declaration in procedure p should cause a compiler error, because 
it is illegal to use an identifier within its own declaration (except for pointer 
identifiers). However, the error is not detected by the conpiler. The effect is 
that U« value of the glctoal constgfit ten is used in defining the local cmstant 
terv ^id the writeln staterrent writes "10". 

A more serious enomaly of the s^ne kind is illustrated by the following 
program: 

program cscope2; 
const red=l; violet=2; 

procedure q; 
type arrayType=array [red.. violet] of integers- 
colors (violet, blue, green, yellom, orange, red); 
var arrayVar : ai'r ayType; c: color,* 
begin 
arrayVar[l):=l; 
c:=red; 

witeln(ord(c)) 
end; 

begin 

q 

end. 
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Within trie procedure q, the global constants red and violet are used to define 
an array index type; the effect of ana)(iedL.violet] is equivalent to ana)(l^]. 
In the declaration of the type color, the constants red and vicflet are locally 
redefined; they are r« longer equal to 1 and 2 respectively—instead they are 
constants of type ccflor with ordinalities 5 and respectively. The writeln 
statement writes "5". 

The use of red in tfe declaration of the type color should cause a compiler 
error t)ut does not 

Consider the statemwit 

aiTayVar[l]:=l; 
If this statement is replaced by 

arrayVar [red] : =1; 

a corrpiler error will result, as red is now an illegal index value for arrs^Var 
—even though arrayVar is of type arraylype and arrayType is defined by 
anB)(ied_violet]. 

To avoid this kind of situation, avoid redefinitim of constant-identifiers in 
enumerated scalar \.yp&%. 

B2. Scope of Base-Types for Pointers 

Consider the following program: 

program pscopel; 

type s=0..7; 

procedure nakecurrent; 
type sptr=*s; 
s=record 
ch:char; 
txiol: boolean 
end; 
var current :s; 
ptrsrsptr; 
begin 
nei»(gtrs); 
ptrs recurrent 
end; 

begin 

nakecurrent 
end. 

Htere we have a global type s, which is a SLft}rsBige of integer; we also have a 
local type s, which is a record-type. Within the procedure makecurrent, the 
type sptr is defined as a pointer to a variable of type s. The intention is that 
this sixxild refer to U« local type s, ctefined on the next line of the program; 
unfortiffiately, however, Vns compiler does not yet krraw atMxit the local type s 
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and uses the global type s. Thus ptrs becomes a pointer to a variable of type 
0l7 instead of a pointer lo a record. Consequently the statement 

ptrs := current 

causes a compiler error since pin* and current are of incompatible types. 

To avoid this kind of situation^ re-declare the type s locally before declaring 
the pointer-type sptr based on s. Alternately, avoid re-declaration of 
identifien that are used as base- types for pointer- types. 
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Syntax of the Language 



C.1 Tokens and Constants C-1 

02 Blocks C-4 

C3 Data Types C-5 

C-ft Variables C-9 

C.5 Expressions C-10 

C.6 Statements C-12 

C.7 PiDcedures and Functions C-15 

C.8 Programs C-16 

a9 Units C-17 



Syntax of the Language 



This appendix collects the syntax diagrams found in the main sections of this 
manual. See the Prefsce for an introduction to syntax diagrams, 

C.1 Tokens and Constants (see Chapter l) 



letter 



(a) tJim/gh (z), (a) tfrwugh (z) 



^9it ^ 



(?) througt) 



hex-di'a/t 



y-^ l digit I J- 

^ (a) throuah (^ -^ 



identifier 



letter 



T 



"^ 





letter 


^ ^ 


^ 






digit 


^ J 


^ 








\ 


unders 


core 


^ 



Oialt-secH^fKie 



digit 



7"- ^ uigii I — ^ 



hex-digjt-seauence ^ . .... ^ 




v^ ^ 
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Syntax 



unsicyied-integer 






digit-sequence 



hex-digit-sequence 



7 



sign 



€> 




unsJgnea-ieai 

— ► 



digit-sequence 



-•Y»(7)> digit-sequence -«r — / • 

^ W scale-factor-^ 



scale-factor 



■© 



u^TT^i 



Sign 



VT 



digit-sequence 



anslgnecf-numOer 



^ 



unsigned-integer 



unsigned-real 



slgnecf-numcer 



^^ sign — ' 



unsigned-number 



qutotect-strfng-constant 



■O 



i; 



string-charoDter 



^ 



<y* 
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Syntax 



string-character 



any cttar except Qj arCR 



T—^ any char 
► 



r^ 



-oo — 

quotea-oharacter-consunt ^(7y ^ string-character | -»-0-» 



constant-declaration 



^ Identifier 



constant 



constant 



T 



^^ slan -^ 



constant-identifier 



^ 



signed-number 



^*> quoted-string 
^ quoted-cnar - 



v^ 
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Syntax 



C.2 Blocks (see 

aock 


Chapter 2) 




■\ 


— ^ laoei oeciaraiion-pari — >^ 




J 




'" 




^^ constant-declaration-part — n^ 




J 




r 




H^ type-declaration-part — \^ 




J 




r 




^"^ variable-declaration-part — v^ 




J 




r 




^^ procedure-and-function-declaration-part — >^ 




J 




^ 




V ^ 1 1 X ^ ^ 


labeJ-dec 
1 

label ^ 


* Statement part ^ 


VaratJon-part 


hi 1r*v»1 > ^ l-^hn1 fcf - 1 .........^ 


►v^iauei^ ^ w laoei ^y ^V'v 


(^ r^ ^ 


w^ 




constant- 




-OsclaiatJon-part 


^»-._*^ ^ X X -> 1 x> k. 


^\1 


onsij ^ !► constEot-deciaration '>^ ► 


V- J 



type-declaration-part 



-» { type) 7 — » type-declaration — ^ — ► 
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Syntax 



{/ariable-declaration-part 

— <^ 



^ 



variadle-declaration 



7 



pwcedure-md-function-cteclaration-part 
T 



XI 



procedure-declaration 



function-declaration 



"Y 



staterr^nt-part 



compound-statement 



C3 Data Types (see Chapter 5) 



type-aeclaraUon ^ 



identifier 



•<^)— M"^ype1 — KT>—» 



tyge_ 






simple-type 



structured-type 



pointer-type 



^--^ 



slrwle-tvpe 



■^ 



ordinal-type 



real-typ© 



^-^ string-type 



^ 



real type ^i real-type-identifier 
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Syntax 



orcfJnal-type 



"\ 



subrange-type 



enumeraled-type 



ordinal-type-identifier 



sti!ng-type 



(^ string } — »(X)— » [lize-attrlbute "| — »0[)--7 ► 



string-type-identifier 



sfze-attriOute 



^ unsigned-integer 



enumeratea-type ^Qy^ identifier-uiTj-X) 



identifier-list 



identifier 



Tir luenuTier — ^r 

^ — O-^ 



sU,iBnqe-type » |^^;;^^;rh »0-» | constant 
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Syntax 



strucUaecf-tvpe 



W( ^ packed) --^ ^— ♦ 



array- type 



7 T 



set-type 



file-type 



record-type 



structured-type-identifier 



array-type 



I 



--»{ ^array} -»(rW-» | index- type ] --Y»(X)~K^QO~ H"^yP^ 



o 



J 



^^-^-^^ » U ^dinal-type 



recojrf-t^ » ( 7^^^ 



^ field-list k-^ 



►(end)-»- 



fieia-ilst 



■~\ 



fixed-part 




variant-part 




flxea-part 



7— ► field-declaration — ^ 

^ O* ^ 



field-declaration 



identifier-list — KjJ — ^ ^VP® 
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Syntax 



variant-part 
—^ (cecse) 



^ IclentlfleTI XTV 



lag-field-lype -^(^ 



I 



variffit 




taQ-field-tj^je 



ordinal-lype-identifier 



variant 



^ constant | --y»(7>(( )' V — r»())-» 

I n\^ J Wj field-list K 



O 



^^~^yP^ — ►(^r)-»(^of)-» | ordinal-type 



fne-type ^ ^^^ 



^-»(or)-» | type [ -^ 



/^//7/6>/-/^ K3)-.»{^^^ 



^ IK 



pointer-type-identifier 



TT 



base-type ^ type-identifier | ► 
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Syntax 



a4 variables (see Chapter 4) 



[/arlable-declaratlon 



identifier-list | -K7)~ H ^VP^ l ~K7) ^ 



{/arlaijle-refierence 

► 



variable-identifier 



^ qualifier k-^ 



variable-identifier 



^► ictentifier 



qualifier 



■^ 



^>-> 



index 



field-designator 



^ 



file-buffer-symbol 



^ pointer-object-symbol 



index 



*<X)-r-H 



expression 



O 



r 



a>-^ 



field-desianator 



O 



identifier 



flle-txjffer-symtxjl 



O 



pointer-oDiect-symt)ol 



<!> 
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Syntax 



as E>q[>ie$sions (see Chapter S) 

unsigned-constant 



T 



^ 



'v^ 



unsigned-number 



quoted-strlng-conslant 



constant-identifier 



-<rtr> 



■^ 



> 



j^ 



factor 



'v. 



^^ 



v§>^ 



variable-reference 



^^ 



^ 



unsigned-constail 



function-call 



set-constructor 



»(T)-> expression -KT)" 
►(not)-» factor 



^ 
■> 



^ 



^-^ 



term 



7 — ► factor 






-(mocTK 



^ 



sJnv]e-e.>^wssIm 



^sion K 



"7^ 



^ 



* term 



O- 
<5> 
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Syntax 



expression 



simple-expression 






simple-expression 



fijncUon-cail 

^ 



function-identifier 



T^i 



actual-parameter-list 



TT 



acu/al-oarameter-ilst 



actual-parameter 



<(> 



c 



actual-parameter 



(S> 



o 



y-Kl^-^ 



1i 



expression 



variable-reference 



"> 



^-^ 



procedure-identifier 



^ function-identifier 



L_^ 



set-constructor 



<S> 



X 



c 



member-group 



O 



J 



T 



<I> 
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Syntax 



memt)er-awuD 



expression 



W{Ty-» expression -^ 



C.6 Statements (see Chapter 6) 

statement 



^ label [ -^Q-^ "^^ 



T 



simple-statement 



^ structured-statement 



T 



JabeJ 



^ digit-sequence 



simpJe-statement 






^ 








^" — ► procedure-statement > 








L ^ 




w yj^yXi siaicmcnx. 





assignment-statement 



x:^ 



variable-reference 



function-identifier 



— U(ir 



(7-) — » expression 



ptTDceckJie-statement 
^ 



procechjre-identifier 



^ 



actual -parameter-list 



TT 



qoto-statement » ( jii;)-»[li^ 
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structurea-statement 


^ 










^ 






J ■> 

^ 


k, 






conditional-statement 






repetitive-statement 






wltn-statement 








^ 











compound-Statement 
» ( begin > 



■7 ^ Statement { — ^ 



► (end) - 



O 



concfJtlonal-statement 



> — ^ 



if-statement 



case-statement 



SI. 



If-statement 



<»H 



expression 




D 



then 



statement 



^-» (else) -» statement -^ 



case-st3tement 




» (case) — » expression -"»(of)-N 



otherwise-clause 



►(^)-^ 



£»$)£» 



-;?— ► constant --%r Ki)~^ statement 



o 



otherwise-dausB 



»(7)-» (otherwise ) -» statement 
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repetitive-statement 



repeat-statement 



while-statement 



^ for-statement 



rq:^3t-statement 



»( ^ repeat ^ 7^ statement -<r — ►( ^until^ — > expression] — ► 



-G> 



wnue-statement 
^ ^ while) — ► expression | — ►(do) — ► statement 



for-statement 

»(^for^)-» control-variable ~^\^y-^ initial-value 



c 



D 



^"-» (^downto) -^ 



final -value -♦(S)-^ statement 



control -varJabJe 



► variable-identifier ► 



initial-value 



expression 



final-value 



* expression ► 



with-stat^n&it 



— » (with) y^ 



record-varlable-reference 



O 



T 



<*>-» 



statement 
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C.7 Procedures and Functions (see Chapter 7) 

pjiicealufe-alea/a/atJor? 



procedure-heading -^\7)-^ procedure-body -^\i) — ► 



procedure-ixKiy 



"^ 



block 



v^ 



> ( foivard 
► ( external / ■ 



k. 



piTxeckJie-lw^fg 



-» ( procedure ) — ► identifier 



T^i 



formal-parameter-list 



TT 



function-declaration 

function-heading -♦{7)-* function-body -KT) — ^ 



function-Coay 



■^ 



block 



^ 



► (forward 
^external/- 



funcuon-neaoinq ». (^;;;^5^;^) > |i5;^;^i^ 



c 



D 



u 



formal-par£H7ieter-list 



— T'-^vy"^ result-type 



result-type 














^ 


1 




>. 
















— w rcai"iypc""iucnuricr 


> 








v^ 




V 








— ^ poinier-i,ype-iaeni.iTier 
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fonjya]-parameter-Jj'st 



paranneter-cieciarailon 



T — Y 



""^ procedure-heading 



^ 



^ function-heading 



O 



<)>- 



par&wter-ileciaraUon » |~i^nUfier-list h ^Q- H type-idenUfier 



C^ Programs (see Chapter 8) 



program-heading -KT} 



^ uses-clause >\^)r 



block 



pjvgram-heactlng 



— »(pn)gramy» Identifier 



Vdh 



program-parameters 



K2>^* 



p/apa7>Taa/a7»gte^ »| IdenUfler-llst 



uses-Clause 



•»{uses) ► 



identifier-list 
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C.9 umts (see Cttapter 9) 

regular-unit 



unit 



it-heading — ^\y) 



Q 



Interface-part -^ implementaUon-part -Wend 



3 



Ljnit-neactinq ^f^j^TV ^ldi^^tifii? 



interface-part ^ l^^^^^^^y 



J 



^ 
^ 



uses-clause 



D 



constant-declaration-part 



D 



type-declaration-part 



^ 



D 



variable-declaration-part 



r^ 



D 



^ procedure-and-function-declaration-part 



A> 



implementaaon-part ^(^ ImplementatiorTy 



T 



''^ cOTistant-cteclaration-part 



r 



^ type-declaration-part 



b 



r- 



D 



^ 



variable-declaration-part 



D 



^ procedure-and-fmction-declaration-part — ^»^ — ► 
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D.l Preface 

This appendix describes Pascal real arithmetic and two Lisa intrinsic units, 
FPLib and MathLib. FPLib is a Pascal interface for SANE (the Standard 
Apple Numerics Environment). MathLib contains various mathematical 
routines^ including routines for sorting, formatting, financial analysis, zero 
finding, and linear algebra. 

This appendix refers to two documents: 

- The Standard tipple Numeric EnK''ironment 

■ The 6800CI /^semhJy-Language S/^NE Engine 

These documents are Parts I and III of the /^ppJe Numerics Manual, and are 
included in the third volume of this set, the System Softwai-e Manuals. (Part 
II of the ^pple Numerics Manual,. The 6X^2 /^sembly-Lmguage Sf^NE Engine, 
is not included in this set.) 

Linking: When using Pascal real variafcJes or constants or the units FPLib or 
MathLib, you must include lOSFPLib, in addition to lOSPasLib, in your list of 
files to be linked. 

hiacintosh 

Pascal programs can be compiled on the Lisa to run on the Macintosh. 
Floating- point usage is slightly different, and some restrictions apply, as 
described in Section D.5. 

D-2 Pascal Real Arithmetic 

D.2.1 IntroductlCMn 

Lisa Pascal real arithmetic conforms to as many of the requirements of a 
single-precision implementation of IEEE arithmetic as can be expressed in 
the standard Pascal language syntax. IEEE arithmetic is described in j4 
Proposed Standard for Binary Floating-Point P^ithmetic, Draft 10.0 of IEEE 
Task P754, December 2, 1982. 

SANE (the Standard Apple Numeric Environment), which contains a 
completely conforming extended-precision implementation of IEEE arithmetic, 
is in the intrinsic unit FPLib. FPLib, which also contains elementary 
functions, and MathLib, which contains the higher mathematical procedures 
used in LisaCalc and Lisa BASIC, are in the file lOSFPLib. FPLib and 
MathLib ai^e described in Sections D.3 and D.4 of this appendix. 

If, however, you only wish to use the features of Pascal real arithmetic as 
defined in the Pascal language standard, you do not need to use either of 
these units in your source code. Pascal real arithmetic will then operate 
according to the default modes for IEEE single-precision arithmetic. IEEE 
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arithmetic works like conventional floating-point arithmetic^ except 
sometimes it works better. In particular, results are defined for all 
floating-point operations; invalid operations never terminate execution and 
always supply appropriate results. When examining printed results produced 
by a write of a real variable: 

■ A number that looks normal is a faithful representation, within the 
format specification, of the binary number held internally. 

- "0" or "-0" represent exactly zero with positive or negative sign 
respectively. Positive and negative zeros behave identically most of the 
time, but 1/0 yields positive infinity and l/(-0) yields negative infinity. 

- "INF" or "-INF" are the representations of positive and negative infinity. 
They can be produced by floating-point overflow as well as by division 
by zero. 

■ "NaN" or "-NaN" represent Not-a-Number, used to represent an 
undefined or erroneous value. Often the representation includes a 
parenthesized NaN code; for instance, *nrite(sqrt(-l)) produces 
'NaN(l)." NaN codes are described in The Standard ^pple Numeric 
Environment. 

Normal numbers that are printed with nine or more significant digits can be 
read back in to produce the same binary value. The strings printed for 
infinite and NaN values are accepted by read, and produce the same binary 
real value that produced the string. The strings for infinity and NaN are not 
accepted by the Compiler as real constants in Pascal source code, however. 

D.2.2 Rounding 

When the result is not representable exactly as a real value, then it is 
rounded to the nearest representable real value. If the result is exactly half 
way between two representable real values, then it is rounded to the even 
representable value which has a zero in its least significant bit. 

D.2.3 Infinity Arithmetic 

Infinity arithmetic obeys common mathematical conventions as indicated in 
the tables on the following page. 
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Table D-1 
Results of Addition and Subtrection on Infinities 



Left 



Right 
Operand 



Operand 




-INF 


finite 


+INF 


-INF 
finite 
+INF 


+ 


-INF 
-INF 
NaN 


-INF 

finite? 

+INF 


Na^^J 
+INF 
+ INF 


-INF 
finite 
+INF 


— 


NaN 
+ INF 

+INF 


-INF 
finite? 

+INF 


-INF 
-IMF 

NaN 


? Result is infinite if the operation overflows. 



Table D-2 
Results of Ivhjltiplication and Division on Infinities 



Left 




Right 
Oper&id 




Operand 


iO 


finite 


iINF 


±0 
finite 
±INF 


* 


-0 
NaN 


±0 

finite? 

tINF 


NaN 
±IMF 
iINF 


finite 
±INF 


/ 


NaN 
iINF 
iINF 


tO 

finite? 

iINF 


NaN 


? Result is infinite if the operation overfloir'/s. 


Mote: Sign of result is determined by signs of 
operands in the usual manner. 



D.2.4 NaN Arithmetic 

NaNs are produced as the result of an invalid operation such as sqrt(-l), 
INF-INF, 0/0, 0*INF, In(-l), or sin(INF). If one or more NaN is an 
operand to any operation that produces a floating-point result, that result 
will be a NaN. 
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Comparisons involving NaNs are never less than, equal to, or greater than; 
they are always unequal. So if x is a NaN, xOy will be true, while x<y, 
xiy, x=y, x>y, and x>y will always be false regardless of y. "If xOx" is a 
good test of whether x is a NaN. 

Round and trunc operations upon NaNs produce undefined values since 
integers do not have NaN values. Round and trunc of numbers too large to 
represent as integers also produce undefined values. 

D.3 FPLib 

D.3.1 Introduction 

This section describes the Lisa intrinsic unit FPLib, which is a Pascal 
interface foi- SANE (the Standard Apple Numeric Env/ironment). SANE in turn 
implements P754, the proposed IEEE Standard for binary floating-point 
arithmetic. 

SANE data types, operations, and exceptions are described in detail in The 
Standard Apple Numeric Environment. This section describes only the FPLib 
interface for Pascal programs. The FP68K interface for assembly-language 
programs is described in The 68(XX> Assembly-Language SANE Engine 

If you are familiar with Pascal, you should be able to use most of FPLib just 
on the basis of the comments in the interface in Section D.3.12. 

When writing Pascal source code, include a uses statement such as: 

USES FPLib; 

after the program statement in a main program or after the interface 
statement in a unit. 

The two examples that follow, a program and a unit, illustrate the use of 
FPLib. We encourage you to type in these examples, to compile them, and, 
in the case of the program, to execute the code file while following this 
discussion. 

Example 1 

This program reads an input string representing a floating-point value and 
echoes it to the screen. It demonstrates the use of SANE data types, and 
how values can be accepted on input and displayed on output. 

porogram EchoNumbex; 

Uses 
FPLib; 

Var 

InStr, ChjtStr : DecStx; { Input and output strings. } 

X : Single; { Single value of InStr. } 

f : DecFoiiB; { Specifies output format. } 
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begin { EchaNinber } 

f. style := FLOATDECIMftL; { Floating output foiinat. } 

f .digits := 9; {9 significant digits. } 

write ('Enter nunber: '); 

readin (InStr); { Read first input string. } 

while inStr <> " do begin 

Str2S (InStr, x); { Convert input to Single value x. } 

S2Str (f, X, OutStr); { Convert x to string by f . } 

MTiteln (OutStr); 

write ('Enter mirtjex: '); 

readin (InStr) { Read next input string. } 

end 

end { EchoNunber } 



In the program EchoNumber, note that: 

■ The input and output strings (InStr and OutStr) are of type DecStr, a 
Pascal string type defined by FPLib. 

■ A variable x of type Single has been declared to hold the value of the 
input string. 

■ The vailable f is of type DecForm, which specifies the f ornnat of the 
output string. In this case^ f is assigned so that the output will be in 
FLOATDECIMAL format {as opposed to FIXEDDECIMAL), and will show 
9 significant digits. 

■ The FPLib routine Str2S converts the ASCII characters from the input 
string InStr to the Single value x. 

■ The FPLib procedure S2Str converts the Single value x to the output 
string OutStr. The format of this string is "determined by the value of f. 

Throughout FPLib, the names of procedures reflect the data types involved. 
For example, Str2S converts to Single. There are also procedures Str2D, 
Str2C, and Str2X for con-v/erting to the other SA^slE data types Double, Comp, 
and Extended, respectively. 

Now compile and execute the program, trying out various input, values. You 
will note that the input string '0.5' is echoed (as you would expect) as 
'5.00000000E-1', whereas the input value '0.1' is echoed as '1.0000000 IE- 1', 
because of roundoff, as discussed in 57?^ Standard /^pple Numeric 
Environment. 
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Example 2 

The second example shows the use of FPLib from another unit. This example 
also shovz-s how expression evaluation is accomplished using Extended 
intermediate valuables. 

The unit provides a procedure to evaluate the dot product of two vectors. 
The input vectors v and w (of type Vector) are represented as arrays of 
Single values. The desired result is the Single value z. In order to compute 
the value of z with maximum accuracy, all of the intermediate calculations 
ore performed in extended precision. This feature is at the heart, of the 
design of SANE. 

unit DotProd; 

irfTERFflCE 
uses 

FPLib; 
const 

N = 2D; { Size of Vector. } 
type 

Vector = aorray [l-.N] of Single; 
porocedure DotProduct (v,w: Vector; var Z: Single); 

IlfLElCNTflTION 

procedure DotProduct { (v,w: Vector; var Z: Single) }; 
{ Returns the dot product of v and w in z, 
accunulated in Extended and returned in Single. } 

var s, t : Extended; 

i : 1..N; 

begin { DotProduct } 

I2X (0, s); { s <— } 
for i := 1 to N do begin 

S2X (v[iL t); { t <— v[i] } 

llulS (w[iL t); { t <— v[i] * w[i] } 

{ Accumjlate in Extended. } 

ftdtfC (t, s) { s <— s + t } 

erai; 
X2S (s, z) { Produce Single result. } 

erwJ { DotProduct } ; 

end { DotProd } . 
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In the procedure DotProduct, note that: 

■ The sum s is initialized to zero using I2X (I2X provides convenient and 
efficient assignment of integral constants to Extended). 

■ A Single value from v is converted to extended precision in the 
temporary variable t. This conversion is performed by S2X and is exact. 

■ T is directly multiplied b*/ the corresponding value from w^ leaving the 
extended-precision result in t. 

- The sum is accumulated in extended precision by adding t directly to 
the Extended value s. 

■ When the loop completes^ the sum in s is converted, using X2S/ to the 
desired Single result z. 

- In FPLib, all of the basic arithmetic operations on two values ai'e 
two-address operations; that is, the operation is performed on the two 
inputs and the result is stored in the second ai^gument (as in MulS and 
AddX in the example). 

■ All arithmetic operations are pei^formed in extended precision and the 
result is returned in Extended. 

- The names of the procedures again reflect the type of the input 
argument: MulS multiplies an Extended by a Single, AddX adds an 
Extended to an Extended, afid X2S com/erts an Extended to a Single. 

D.3.2 Data Types 

FPLib fully supports the SANE data types Single, Double, Comp, and 
Extended. 

P^cal's 16- and 32-bit integer arithmetic remains distinct from SANE 
ai'ithmetic. However, any program using the FPLib unit can use Pascal 
integer arithmetic. 

D.3.3 Arithmetic Operations 

This section discusses the arithmetic operations add, subtract, multiply, 
divide, remainder, and square root. 

D.3.3. 1 Add, Subtract, Multiply, and Divide 

The arithmetic operations add, subtract, multiply, and divide are provided by 
sixteen procedures: 

Adds, AddD, ftddC, ftddX; 

SubS, SubD, SubC, SubX; 

MulS, MulD, MulC, MulX; 

DivS^ DivD, DivC, DivX. 

Each procedLffe has two operands. The first is always a value parameter of 
type Single, Double, Comp, or Extended, as indicated by the last letter of the 
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procedure name. The second is always a variable parameter of Extended 
type that receives the result. For example, subtraction is provided by the 
procedures SubS (subtract Single), SubD (subtract Double), SubC (subtract 
Comp), and SubX (subtract Extended). If x and y are declared by 

vaor X : Sir^le; 
y : Extended; 

then the statement 

SubS (x, y); { y <— y - X } 

causes x to be subtracted from y and the extended-precision result to be 
stored in y. 

Example 

To compute q = a / b , where a, b, and q are of type Double, declare: 

var ^ b, q : Double; 

t : ExteraJed; { extendi temporally } 

and write: 

D2X (^ t); { t <~ a } 

DivD (b, t); { t <— a / b } 
X2D (t, q); I q <- t } 

D.3.3.2 Remainder 

The remainder operation is provided by 

prcM:edure RenX (x : Extended; venr y : Extended; var quo : integer); 

The remainder, y REM x, is delivered to y. 

The remainder operation determines n, the nearest integer to x/y; if x/y is 
halfway between two integers, the even integer is chosen. Thus, y rem x = y 
- n*x. 

The third argument, quo, delivers the integer whose magnitude is given by 
the seven least significant bits of the magnitude of n, and whose sign is the 
sign of n. (Quo is useful for reducing the arguments of trigonometric 
functions, but can be ignored if not needed.) 

D.3.3.3 Square Root 

The square root operation is provided by 

procedure SqrtX (var x : Extended); 

for any x >= 0. The argument x is both source and destination. 



D-8 



Pascal Reference Manual FIosAing-Point f^ithmetic 

Example 

To find V = square root of u , where u and v are of type Single, declare 

vaor u, V : Single; 

t : Extended; { exteruted tenpooraiy } 

and write 

S2X (U, t); { t <— u } 

SqrtX (t); { t <— sqrt (u) } 

X2S (t, v); { V <— t } 

D.3.4 Conveisions 

D.3.4.1 Conveirsions to and from Extended 

Conversions between the Extended type and the other numeric types 
recognized by FPLib are provided by the procedures 

I2X - integer to Extended 

L2X - longint to Extended 

S2X - Single to Extended 

D2X - Double to Extended 

C2X - Comp to Extended 

X2X - Extended to Extended 

X2I - Extended to integer 

X2L - Extended to longint 

X2S - Extended to Single 

X2D - Extended to Double 

X2C - Extended to Comp 

For example, if x and y are declai-ed by 

var X : Zamft} 

y .- Extended!; 

then to convert a Comp-format value in x to an Extended-format in y, write 
C2X (x, y); { y <_ X } 

D.3.4.2 CtMriv/ersions Between Binary aid Decimal 

Converting Decimal Strings into SANE lypei& 

The procedures Str2S/ Str2D, Str2C, and Str2X convert numeric strings into 
Single, Double, Comp, and Extended formats, respectively. 
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Example 1 

To assign -0.0000253 to an Extended variable %, write 
var X: Extended; 

Str2X (•-2.53E-5', x); { or Str2X ('-0.0000253", x); ) 

The Standard f^pple Numeric Emnronment describes numeric string syntax. 

Corvertir^ SANE Types into Decimal Strings 

The procedures: S2Str, D2Str, C2Str, and X2Str will convert a Single, Double, 
Comp, and Extended, respectively, into a numeric string (of type DecStr). As 
any numeric value can have many decimal representations, you must specify 
the decimal result format. To do so, pass a record of type DecForm, shown 
below: 

Decromi = record 

style : (FLOATEEEIMAL, FIXEDDECIMAL); 
digits : integer 
end; 

Example 2 

To print the value of a Double variable y using a fixed-point decimal format 
with ten digits to the right of the decimal point, write: 

venr y: Double; 
S: DecStr; 

f: DecFoHIB; 

f -style := FIXEDDECIMftL; 
f. digits -.= 10; 

b2Str (f, y, s); 
voriteln ('y = ', s); 

Numbers that round to zero in the specified DecForm are converted to the 
string ' 0.0' or '-0.0'. NaN's are converted to the string ' NaN', '-NaN', 
' NaN(n)', or '-NaKn)', v/here n is a NaN error code in decimal. Infinities 
ai^e con\/erted to the string ' INF' or '-INF'. 

All other numbers behave in an intuitive manner as long as the DecForm 
specifies no more than SIGDIGLEN-1 significant digits. Otherwise, the 
formatted number is padded with zeros where necessary. If the resulting 
string has more than DECSTRLEN characters, the number is represented in 
floating-point notation. (SIGDIGLEN and DECSTRLEN are specified in the 
interface to FPLib.) 

All string results have either a leading negative sign or a leading blank (thus, 
columns of numbers will line up regardless of sign). 
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Decimal Record Conv/ersions 

The Decimal record type is specified in the interface as below: 

Si^ig = string [SIGDIGLEN]; 

Decimal = record 

sgn : 0..1; { Sign (0 fcxr pos, 1 foor neg). } 
exp : integer; { Exponent. } 

sig : SigOig { String of significant digits. } 
end; 

The procedLQ-es S2Dec, D2Dec^ C2Dec, and X2Dec each con^,/ert a Single, 
Double, Comp, or Extended value, respectively, into a record of type 
Decimal. A DecForm operand (shown in the preceding section) specifies the 
format of Decimal. The maximum number of ASCII digits delivered to sig is 
SIGDIGLEN- 1, and the implied decimal point is at the right end of sig, with 
exp set accordingly. Further formatting details are given in Tfre 6W00 
fissembly-Language SANE Engine. 

The procedLQ-es Dec2S, Dec2D, Dec2C, and Dec2X convert a Decimal record 
into Single, Double, Comp, and Extended, res:pectively. The sig pert of 
Decimal accepts up to SIGDIGLEN- 1 significatit digits, with an implicit 
decimal point at the right end of the significant digits. If SIGDIGLEN digits 
are passed, then the implicit decimal point is between the digits at 
SIGDIGLEN- 1 and SIGDIGLEN; the last digit, if nonzero, represents one or 
more nonzero digits in the SIGDIGLEN or subsequent positions. Further 
details of the representations of Decimal input values for these routines are 
given in The S&CW Assembly-Lafiguage Sf^NE Engine. 

D.3.5 Expression Evaluation 

SANE floating-point arithmetic (and the FPLib unit) is designed to operate on 
Extended values. For example, DivD (x, y) operates on the Extended-format 
value in y by dividing the Double-format number x into y and leaving the 
result in y. To evaluate more complicated expressions. Extended temporaries 
can be used. 

The following examples illustrate extended-based expression evaluation. The 
first example uses an Extended accumulator to store the results of all 
operations. 

Example 1 

Compute the value of 

r = (a+b-cl*d-«-e 
f 

where all variables are of Double type. 

var % b, c, d, e, f, r : Double; 

t : Extended; { extended temporaiy } 
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isegin 



D2X (a, t); 


t <— a 


ftddD (b, t); 


t < — a + b 


SubD (c, t); 


t < — a + b - c 


MulD (d, t); 


t <— (a + b - c) * d 


ftddD (e, t); 


t < — (a + b - c) * d + e 


DivD (f, t); 


t <— ((a + b - c) ♦ d + e) / f 


X2D (t, r); 


{ r <- t } 



Mote that although the arithmetic style is extended-based, not every operand 
need be converted to Extended. In the example, only one explicit conversion 
to Extended was required. 

Example 2 

Compute the value of the root r of larger magnitude of a quadratic equation 
from the formula: 



b + sign{b) * sqrt( b^ - 4 * a * c ) 



r = 



2 * a 

where a, b, c, and r are of Single type. 

var a, b, c„ r : Single; 
tl^ t2, t3 : Extended; 



{ extended tenpfxraries } 



begin 



S2X (b, tl); \ 


tl <- 


- b } 


t3 := tl; 


t3 <- 


- b 


MUIS (b, tl); 


tl <- 


- b*2 


I2X (4, t2); 


t2 <- 


- 4 


Mills (a, t2); 


t2 <- 


- 4 * a 


MulS (C, t2); 


t2 <- 


- 4 ♦ a • c 


SubX (t2, tl); 


tl <- 


- b*2 - 4 • a ♦ c 


SqrtX (tl); \ 


tl <- 


- sqrt (b*2 - 4 • a ♦ c) 


CpySgnK (tl,t3); \ 


tl <- 


- same with sign of b 


ftddS (b, tl); \ 


tl <- 


- b + sign(b) ♦ sqrt (b*2 - 4*a*c) 


NegX (tl) ; \ 


tl <- 


— (b + sign(b) ♦ sqrt... 


S2X (a, t2); \ 


t2 <- 


- a 


Adds {% t2); \ 


t2 <- 


- 2 ♦ a 


DivX (t2, tl); 


tl <- 


- -(b + sign(b) ♦ 

sqrt (b*2 - 4 ♦ a * c)) / (2 ♦ a) } 


X2S (tl, r); 


[ r <- 


tl } 
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The smaller root may then be computed by evaluating the formula c/(a*tl) in 
extended. Exceptional cases include b^ < 4 * a * c and a = 0. 

Example J 

Evaluate the polynomial 



Co + Ci * X + C2 



+ Cn 



and its derivative 

Dy = ci + 2 * C2 * X + 3 * C3 * x2 + . . . + n * Cn * x<"-i) 

where the coefficients cq through Cp ai'e stored in an array of Single and x., 
y, and Dy are of type Single. 

const rtlflX = 100; 



var n, i : O..NMflX; 
X, y, Dy : Single; 
c : array [0. .tflAX] of Single; 
tl, 
t2, t3 .- Extended; 

i2X (0, tl); 
t2 := tl; 

for i := n doMfito 1 do b^in 



{ tl <— c [i] + X ♦ tl 

MulS (x^ tl); 

ftddS (C [i], tl); 

{ t2 <— tl + X ♦ t2 : } 

MulS (X, t2); 
S2X (c[iL t3); 

HulS (i, t3); 

ftddX (t3, t2) 



} 



end; 

{ tl <— c [0] + 
MulS (x, tl); 
flddS (c [0], tl); 

X2S (tl, y); 

X2S (t2, Dy); 



tl : } 



{ For computation of y. } 
{ For conputation of Dy.} 



{ tl <— 
{ t2 <— 



{ tl <- 
{ tl <- 



X • tl 
c [i] H 



tl 



{ t2 <— X * t2 



{ tl <— X * tl 
{ tl <— c [0] + tl 

{ y <— tl 

{ Dy <— t2 
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The method, called Horner's Rule, used to evaluate the polynomials is based 
on the polynomial representation 

y = ( ... ((Cn * X + Cn-i) * X + Cn-2) * X + ... ) * X + Co- 

It is faster and more accLffate than the straightforward computation 
suggested by the standard representation, shown at the beginning of the 
example, and is conveniently implemented using SANE's extended-based 
arithmetic. 

D.3.5.1 Global Constants 

To speed up execution, frequently used constants can he defined globally 
(outside the routines). For example, if pi is declared and defined by.- 

var pi : Extended; 
begin 

Str2X (•3.14159263358979323846', pi); 

then executing 

X := pi; 

is significantly faster than 

Str2X ('3.14159265358979323846*, x); 

Defining constants globally is particularly helpful when the definition is via 
one of the string conversion routines, such as Str2X- For conversion of 
integers, I2X and L2X ai'e significantly faster than Str2X. 

D.3.6 Comparison Functions 

Any two floating-point values in the Extended format can be compared using: 

function CtopX (x : Extended; r : RelOp; y .- Extended) : boolean; 
or 

function RelX (x, y .- Extended) : RelOp; 

The RelOp values are 

GT greater than 

LT less than 

GL greater than or less than 

EO equal 

GE greater than or equal 

LE less than or equal 

GEL greater than, equal, or less than 

UNORD unordered 
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Single^ Double, or Comp values can be compared by first converting them to 
Extended. 

For every pair of operand values, exactly one of the relations LT, GT, EQ, 
and UNORD is true. The value of RelX is the appropriate one of these four 
relations. CmpX (x, r, y) is true if and only if the relation x r y is true. 

Example 

If p is gi-eater than q then print 'p > q is TRUE'; otherwise, print 'p > q is 
FALSE'. 

var p„ q: Extended; 

ir OnpX (p, GT, q) then 

MTlteln Cp > q Is TRUE") 
else 

writeln ('p > q is FALSE'); 

Note that equivalent results are produced by 

if QipX (p, l£, q) or QnpX (p, UNDRD, q) then 

MTiteln Cp > q is FftLSE') 
else 

vnriteln ('p > q is TRUE'); 

or by 

case RelX (p,. q) of 

GT: vnriteln ('p > q is TRUE'); 

LT, EO: woriteln ('p > q is FALSE'); 
(JNORD: begin 

SetXcp (INVALID, TRUE); 

vnriteln ('p > q is FALSE') 
end { UNDRD } 

eral; { case RelX } 

D.3.7 Infinities, NaNs, and Denormalized Numters 

In addition to the normalized numbers supported by most floating-point 
packages, FPLib fully supports the special values— infinities, NaNs, and 
denormalized numbers— specified by the IEEE Staridard, as described in The 
Standard tipple Numeric Environment. 

D.3.7. 1 Inquiries: NumClass and the Class Functions 

The functions ClassS, ClassD, CiassC, and ClassX can be used to classify the 
value of a vai-iable. These functions ai-e of type NumClass: and return one of 
the values: 
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SNAN 


- signaling NaN 


ON AN 


- quiet NdS 


INFINITE 


- infinity 


ZERO 


- zero 


NORMAL 


- normalized number 


DENORMAL 


- denormalized number 



The class functions also return the sign of a value in the paranneter 
var sgn-. integer. 

D.3.8 Environmental Control 

Envii^onnrjental controls supported in FPLib include the rounding direction, as 
well as exception flags and their corresponding halts. Rounding precision is 
supported in the MathLib unit. 

D.3.8. 1 Ftoundir^ DirecticMi 

The rounding directions are of the type 

RounfDir = (TdCflREST, UPWiD, DOMNHflRD, TOWflRDZERD) 

The rounding direction is set by the SetRnd and SetEnv procedures and can 
be interrogated by the GetRnd function. 

Example 

The connmon rounding function specified by 

( trunc (x + 0.51, if x >= ***insert bracket*** 

Rnd (x) = i 

\^ trunc (x - 0.5), if X < 

can be implemented by: 

function Rndl (x : Extended) : inte^r; 

{ Sets INVftLID and returns -32768 if 

X is a N^ oar x <= -32768.5 or x >= 32767.5. 

Sets IhEXflCT if 
-32768.5 < x < 32767.5 and x is nonintegral. 

Sets no other exceptions. } 

var t : Extended; 
i : integer; 
r : RoundDix; 
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begin { Rnd } 

Str2X ('0.5', t); 
CpySgriK (t, x); 

X := GetRnd; 
SetRnd (TQIMRD2ER0); 
AddX tx, t); 
X2I (t, i); 
I2X (i, t); 

SetXcp (IhEXflCT, not 

SetRnd (r); 
Rnd := i 

end { Rnd } ; 



(QnpK 



t < — +0.5 if X > or X is +0 

t < 0.5 if X < or X is -0 

Sad/e rounding direction. 
Set round-towaord-zeoro. 
t <— X + t 
i < — truncate (t) 
No exceptions! 

t, BO, x) or TestXcp (INVALID))) 
Coorrect INEXACT setting. 
Restore rounding direction. 
On INVALID, i < 32768. 



D.3.8.2 Exception Flags aid Halts 

The exception flags eire values of the type 

Exception = (INVALID, UCERFLOW, OVERFLOW, DIVBYZERO, INEXACT) 

These five exceptions are signaled when detected, and if the corresponding 
halt is set, the SANE engine will JSR to the 'halt vector'. The halt vector is 
initially 0, so that halts terminate execution with a bus erroi". However, the 
user can call the procedure SetHlt Address to set the halt vector to the 
address of a user-defined halt-handling procedure. See Section D.3.11 for 
details. 

Initially all exception flags and halts are cleaied. You can examine, set, or 
clear individual exception flags and halts using TestXcp and TestHlt 
functions and SetXcp and SetHlt procedLces. The SetEnv and GetEnv 
procedures can be used to set or get the entire environment (rounding 
direction, rounding precision, exception flags, and halts). 

D.3-8.3 Managing Environmental Settings 

Issues and techniques for managing environmental settings are co-vered in The 
Standard ^pple Numeric Environment. (The Pascal syntax used in the 
examples there does not fully match the syntax in FPLib.) 

The procedure-entry and procedure-exit routines are provided in FPLib fcft/: 

procedure RrocEntry (var er Environ); 
procedure RrocExit (e: Environ); 

Example 

The following procedure signals underflow if its result is denormal, and 
overflow if its result is infinite, but hides spurious exceptions occurring from 



D-17 



Pas-csJ Reference Manuel FloetinQ-Point f^hthmetic 



internal computations. This is Example 3 in Section 8 of The Standard tipple 
Numeric Environment, implemented with FPLib calls. 

poroceduore compares (var x: Double); 
uses FPLib; 

vair e: Environ; { local storage for envirorment } 

c: NuClass; { for class inquiry } 

sgn: integer; { for class inquiry - not used } 

procedure clearxcps; { more efficient version in MatN-ib } 

const FIRSDffP = INVALID; 

LflSTXCP = II€XflCT; 

var xcp: Exception; { for clearing exceptions } 

begin {clearxcps} 

for xcp:= FIRSTOCP to LflSTXCP do 
SetXcp (xcp, FALSE) 
end {clearxcps}; 

begin {compres} 

RrocEntry (e); { save caller's environment and } 

{ set default environment - } 

{ now halts disabled } 

{ conpute result x } 

c := ClassD (x, sgn); { class inquiry } 

clearxcps; { clear possibly spurious exceptions } 

{ now raise specified exception flags: } 

if c = IhFINITE then SetXcp (OVERFLOW, TRIE) 
else if c = DENORMAL then SetXcp (UNDERFLOW, TRUE); 
RrocExit (e) { restore caller's envirctfiient, } 

{ including any halt enables, and } 
{ then signal exceptions from } 

{ subroutine } 

end {compres} ; 



D.3.9 Auxiliary Procedures 

The FPLib unit includes a set of special routines: RintX, NegX, AbsX, 
CpySgnX, NextS, NextD, NextX, ScalbX, and LogbX. 

D.3.9. 1 Round to Integral Value 

An Extended variable can be rounded to an integral value by 

procedure RintX (var x : Extended); 

The result is retttrned in the input x. 
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D.3.9.2 Sign Manipulation 

Procedures NegX, AbsX, and CpySgnX each operate on an Extended variable, 
altering only the sign of the Extended argument. 

The negation operation is provided by 

Fxrocedure NegX (var x : Extended); 
The absolute value operation is prcvided by 

procedure AbsX (var x : Extended); 

An operation to copy the sign of one Extended variable to the sign of 
another is provided b-y 

procedure CpySgnX (var x : Extended; y -. Extended); 

which copies the sign of y into the sign of x. 

D-3.9.3 Next-After 

The procedui-es NextS, NextD., and NextX each generate the next 
representable neighbor in its respective format, given an initial value and a 
direction. The first argument (x) to each of these routines is "bumped" to 
the next representable value in the direction of the second argument (y). 

The procedui-e NextS bumps the Single value x to the next representable 
Single value in the direction of y: 

procedure NextS (var x : Single; y : Single); 

The procedure NextD bumps the Double value x to the next representable 
Double value in the direction of y: 

procedure NextD (var x : Double; y : Double); 

The procedure NextX bumps the Extended value x to the next representable 
Extended value in the direction of y: 

procedure NextX (var x : ExteraJed; y : Extended); 

D.3.9.4 Binary Scale arKi Log 

An Extended variable can be efficiently scaled by a power of two by 

procedure ScalbX (n : integer; var y : Extended); 

The procedure ScalbX computes y * 2", and returns it in y. 

The binary exponent of an Extended variable can be determined by 

procedure LogbX (var x : Extended); 

The procedure LogbX returns in x the binary exponent of x as a signed 
integral value. 

D.3.10 Elementary Functions 

FPLib provides a number of mathematical functions, including logarithms and 
exponentials, two important financial functions, trigonometric functions, and a 
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random number generator. The logarithms and exponentials are provided in 
base-2 and base-e versions. 

D.3.10.1 Logarithms 

The procedLffes Log2X^ LnX, and LnlX each operate on an Extended variable, 
returning the result in the input argument. 

The base-2 logarithm log2 x is computed b-^' 

procedure Log2X (veor x : Extended); 
for any nonnegative x. 
The natural (base-e) logarithm loge x is computed by 

procedure LnX (vaor x : Extended); 
for any nonnegative x. 
The natural (base-e) logarithm loge (1 + x) is computed by 

procedure LnlX (var x : Extended); 
for any x >= -1. 

D.3.10.2 Exponentials 

Procedures Exp2X, ExpX, and ExplX each operate on an Extended variable, 
retwning the result in the input argument. Procedure Xpwrl operates on an 
Extended variable using an integer value, returning the result in the Extended 
input, argument. Procedure XpwrY operates on two Extended variables, 
returning the result in the second input argument. 

The procedure Exp2X calculates 7^ and returns this value to x: 

procedure Exp2X (var x : Extended); 
The procedui-e ExpX computes e^ and returns this value to x: 

procedure ExpX (var x : Extended); 
The procedure ExplX computes e^ - 1 and returns this value to X: 

procechire ExplX (var x : Extended); 
The procedui^e Xpwrl computes x^ and returns this value to X: 

procedure Xp»a:I (1 : integer; var x : Extended); 
The procedure XpwrY computes x^ and returns this value to x: 

procedure XpwrY (y : Extended; var x : Extended); 
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D.3.10.3 Financial FunctiiHts 

FPLib provides two procedLffes, Compound and Annuity., that can be used to 
solve various financial problems. Each of these procedures takes two input 
arguments of type Extended^ and produces an Extended result. The two input 
arguments, r and n, represent in each case an interest rate and a number of 
periods, respectively. 

Compound Interest 

Compound interest can be computed using 

procedure ConpourKl (r, n : Extended; var x .- Extended); 

This procedure computes the value 

X = (1 + r)^ 

where r is the interest rate and n is the number of periods. 

Example 

If $1000 is invested for 6 years at 9^ compounded quarterly, then what is the 
fLiture value of the principal? Compute: 

var r, n, four, years, rate, PV, FV : Extended; 
f : DecFomi; 
s : DecStX; 

with f do begin style := FIXEEOBCIMftL; digits := 2 end; 

I2X (4, four); { four <— 4 } 

I2X (6, years); { years <— 6 } 

Str2X ('0.09', rate); { rate <— 9% } 

I2X (1000, PV); { PV <— 1000.00 } 

r := rate; 

DivX (four, r); { r <— rate / 4 } 

n := years; 

MulX (four, n); { n < — 4 * years } 

Conipound (r, n, FV); { FV < — (1 + r)*n } 

MulX (PV, FV); { FV <— PV ♦ (1 + r)*n } 

X2Str (f, FV, s); { f is FIXED with 2 fraction digits.} 

writeln ('FV = $', s); 

The future value FV is $ 1705.77. 
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Example 

How much must a person invest today at 9^ compounded quarterly to have 
$15,000 in his account in 6 years? Assuming f, rate, years, r, and n have 
values as in the example above, compute: 

var r, n, rm, four, years, rate, PV, FV : Extended; 
f : Decrani; 
s : DecStr; 



with f do begin 

style := FIXEDDECIMftL; 

digits := 2 
end; 

I2X (15000, FV); { FV <— 15000.00 } 

nn := n; 

htegjK (nn); { nn < n } 

Conpound (r, nn, PV); { PV <— (1 + r)*-n } 

MulX (FV, PV); { PV <— FV ♦ (1 + r)*-n } 

X2Str (f, PV, s); { f is FIXED with 2 fraction digits.} 

writeln ('PV = $', s); 



The present value PV is $ 8793.70. 

The present value and future value of an annuity can be computed using 
porocedure Annuity (r, n : Extended; var x : Extended); 

This procedure computes the value 

r 

where r is the interest rate and n is the number of periods. 

Example 

Suppose that a loan at 12^ compounded monthly is to be paid off at a rate 
of $225 per month in 36 months. What is the present value of the loan? 
Compute: 

var r, n, twelve, rate, PV, PHI : Extended; 
f : DecForiD; 
s : DecStr; 
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with f do begin 

style := FIXEDDECIMAL; 

digits := 2 
end; 

I2X (12, t«#elve); { twelve <— 12 } 

StrZX ('0.12', rate); { rate <— 12% } 

Str2JC ('36', n); { n <— 36 } 

I2X (225, PMT); { RfT <— 225.00 } 

r := rate; 

DivX (twelve, r); { r <— rate / 12 } 

Annuity (r, n, PV); { PV <— (1 - (1 + r)*-n) / x } 

MulX (PMT, PV); { PV <— PMT ♦ (1 - (1 + r)*-n) / r } 

X2Str (f, PV, s); { f is FIXED with 2 fraction digits.} 

writeln ('PV = $', s); 

The present value PV is $ -6774.19. 

Exmr^ple 

If $50 is deposited each month to a savings account that pays 12^ 
compounded monthly, what is the future value of the account after 10 yeai's? 
Compute 

var r, n, twelve, rate, years, FV, PMT, t : Extended; 
f : DecFoons; 
s : DecStr: 



with f do begin 

style := FIXEDDBCIMfiL; 

digits := 2 
end; 

I2X (12, twelve); { twelve <— 12 } 

Str2X (•0.12', rate); ( rate <— 12% } 

I2X (10, years); { years <— 10 } 

I2X (50, PMT); { PMT <— 50.00 } 

r := rate; 

DivX (twelve, r); { r <— rate / 12 } 

n := years; 

MulX (twelve, n); { n <— years • 12 } 
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Compound (r, n, t); { t < — (1 + r)*n } 

Annuity (r, n, FV); { FV <— (1 - (1 + r)*-n) / r } 

MulX (t, FV); { FV <— ((1 + r)*n - 1) / r } 

MulX (PHT, FV); i FV <— FWr * ((1 + r)"n - 1) / r } 

X2Str (f, FV, s); { f is FIXED with 2 fraction digits.} 

writeln ("FV = $', s); 

The final value FV is $ 11501.93. 

D.3.10.4 Trigonometric Functions 

The trigonometric functions are provided by the procedures CosX, SinX, 
TanX, and ATanX (arctangent or inverse tangent), which operate on an 
Extended vaiiable and return the result in the input ai-gument. 

The cosine is computed by 

ixrocedure CosX (var x : Extended); 
The sine is computed by 

porocedure SinX (var x : Extended); 
The tangent is computed by 

porocedure TanX (var x : Extended); 
The arctangent is computed b-y 

procedure ATanX (var x : Extended); 

D.3.10.5 Random Numter Generator 

Pseudorandom numbers are pro-v/ided by 

porocedure RandoniX (var x : Extended); 

RandomX uses the iteration formula 

X = (75 * x) mod (231 _ 1) 
A sequence of psuedorandom integral values r in the range 

1 1 r i 231 - 2 

can be genei-ated by initializing an Extended vailable r to an integral value 
(the seed) in the range and making repeated calls RandomX (r); each call 
delivers in r the next pseudorandom number in the sequence. 

If seed values of r are nonintegral or outside the range 

1 < r i 231 - 2 

then results are unspecified. 
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Example 

A procedure yielding a pseudorandom rectangular distribution on (0, 1): 

Exterior to the procedure declare and initialize 

const SEED = 1018375230 { arbitrary seed } 

var P, one, r: Extended; 

begin 

I2X (1, one); { one <— 1 } 

P := one; { P <— 1 } 

ScalWC (31, P); { P <— 2*31 } 

SufiX (one, P); { P <— 2*31 - 1 } 

L2X (SEED, r); { r <— SEED } 

The desired procedure can be v/ritten 

procedure Rami (var x : Extended); 

begin 

RandcmX (r); { r < — randan int value } 

X := X; { X < — r } 

DivX (P, x) { narnalize to (0, 1) } 

raid; 

D.3.11 <=MditionaI FPLib Procedures 

Function SffE.Environ : longint ; { Internal use imly. } 

Procedure InitFPLib ; { Initializes FPLib. } 

Function GetHlt Address : longint ; { Returns halt address.} 

Procechire SetHltAddress ( HltAddress : longint ) ; { Sets halt address. } 

SANE_Environ is for internal use of other FPLib procedures. 

InitFPLib resets the environment and the halt address to default values. 

This initialization occurs automatically at the beginning of the outer block of 
a Pascal main program. InitFPLib may be called later to reestablish default 
conditions if desired. 

The halt address is the address to which control passes when a floating-point 
halt occurs, as described in detail in The 68000 f^embly-Language Sf^NE 
Engine. GetHltAddress and SetHltAddress may be used to obtain the halt 
address. SetHltAddress may be used to change the halt address to the entry 
point of a halt- handling procedure. 

The following demonstrates a sample halt procedure.- 
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type mi scree = Tecaord 

haltexxors : integer; 
ccrpending : integer; 
depending .- longint; 
end; 

prcH^eduore haltroutine 

( vaor nisc : niscr^::; 
src2, src, dst : longint; 
opcfMJe : integer ) ; 

(* Prints out the op mnrd and address paoraiM^ters of the floating- 
point opexation that halted, then displays the naiae of each 
exception that occurred in that operation ami tfhose halt was 
enab led. After perusing this infoomation, the user presses 
RETURN to contimie execution as if no halt had occurred. *) 

var enw : Environ ; 
X : Exception ; 

begin (* haltroutine *) 
RrocEntry(env) ; 

mritelnC Floating point halt taken on op code ', opcode) ; 
writeln(' Destination address ',dst } ; 
writeln(' Source address ',src ) ; 
writ el n( ' 2nd Source address ', src2 ) ; 
writeC Exceptions signaled with enabled halts : ) ; 
SetErv/(iRisc.hal terrors) ; 
for X := IWftLID to II^EXflCT do if TestHlt(x) then case x of 

INVftLID .- writeC Invalid ') ; 

UNDERFLOW : write(' Underflow ') ; 

OVBRFUM : writer Overflow ') ; 

DIVBY2BRD : write(' DivByZero ') ; 

II€XflCT : write(' Inexact ') ; 
end (* case x *) ; 
writeln ; 

writelnC Press RETURN to continue. ') ; 
readln ; 
ProcExit(env) ; 
end (* haltroutine ♦); 

(* Elsewhere in the program ... *) 



(* This code is executed prior to the floating-point operations for 
which the halts are to be enabled. OldDiltaddress is 
declared to be a longint. *) 
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ol(#ilt8ddress := GetHltAchtress ; (* Save old halt address. *) 
SetHltAddress( f](rd4(ihaltroutine) ) ; (* Set new halt address to go to 

haltroutine. *) 

(* Enable halts on 'severe' exceptions. *) 

SetHlt( INVftLID, TRUE ) ; 
SetHlt( OVERFLOW, TRIE ) ; 
SetHlt( DIVBY2ER0, TRUE ) ; 

(* If any of these three exceptlcMis subsequently occur, control 
will pass through haltroutine. *) 
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D.3.12 FPUb Interface 

UNIT FPLib ; INTRINSIC ; 

INTERFACE 

{ Lisa Floating Point Library. } 

{$C Copyright 1983, 1984, Apple Computer Inc. } 

CONST 

{ SAhE: Standard Apple Numeric Environment } 

{ Comments like !A// denote differences frcwi the Apple // and /// SAhE unit 
interface. } 

SIGDIGLEN = 20; { Maximum length of SigDig. !A//: 28 } 

DECSTRLEN =255; { Maximum length of DecStr. !A//: 80 } 

TYPE 

( 

** Nuneric types. 

1 } 

Single = real; { !A//: array [0..1] of integer } 

Double = array [0..3] of integer; 

Camp = array [0..33 of integer; 

Extended = array [0..4] of integer; 

{ 

** Decimal string type and intermediate decimal type, 

** representing the value: 

** (-l)''sgn * Wexp ♦ sig 

_ ___j 

SigDig = string [SIGDIGLEN]; 

DecStr = string [DECSTRLEN]; 
Decimal = record 

sgn : 0..1; { Sign (0 for pos, 1 for neg) . } 

exp : integer; { Exponent. } 

sig : Si^ig { String of significant digits. } 
end; 
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I 

** Modes., flags, and selections. 

** NOTE: the values of the style element of the DecForm record 
** have different names from the Apple // and /// version to 
** avoid name conflicts. 



Environ = integer ; 

RoundDir = (TONEftREST, UPWARD, DOWNWARD, TOWARDZERO); 
RelOp = (GT, LL GL, EO, GE, LE, GEL, UNORD); 
I > < <> = >= <= <=> } 
Exception = (INVALID, UNDERFLOW, OVERFLOtW, DIVBY2ER0, INEXACTl; 
NumClass = (SNAN, ONAN, INFINITE, ZERO, NORMAL, DENORMAL); 
DecForm = record 

style : (FLOATDECIMAL, FIXEDDECIMAL); 

{ !A//: FLOAT, FIXED } 
digits : integer 
end; 



** Two address, extended-based arithmetic operations. 



procedure AddS 


(X : 


Single; 


var 


y 


Extended); 


procedure AddD 


(X : 


Double; 


var 


y 


Extended); 


procedure AdcC 


(X : 


Comp; 


var 


y 


Extended); 


procedure AddX 


(X : 


Extended; 


var 


y 


Extended); 


{ y := y + 


X 1 










procedure Sutfi 


(X : 


Single; 


var 


y 


Extended); 


procedure SufcO 


(X : 


Double; 


var 


y 


Extended); 


procedure SubC 


(X : 


Comp; 


var 


y 


Extended); 


procedure SubX 


(X : 


Extended; 


var 


y 


Extended); 


{ y := y - 


X } 










procedure MulS 


(X : 


Single; 


var 


y 


Extended); 


procedure MulD 


(X : 


Double; 


var 


y 


Extended); 


procedure MulC 


(X : 


Comp; 


var 


y 


Extended); 


procedure MulX 


(X : 


Extended; 


var 


y 


Extended); 


{ y := y * 


X } 










procedure DivS 


(X : 


Single; 


var 


y 


Extended); 


procedure DivD 


(X : 


Double; 


var 


y 


• Extended); 


procedure Di'X 


(X : 


Comp; 


var 


y 


: Extended); 
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procedure DivX (x 
{ y := y / X } 



Extended; var y : Extended); 



function CmpX (x : Extended; 
{ CmpX := X r y } 



r : RelOp; y : Extended) .- boolean; 



function RelX (x, y : Extended) : RelOp; 

{ X RelX y, where RelX in [GT, LT, EO, UNORD] } 



{ 

** Conversions between Extended and the other numeric types, 
** including the types integer and longint. 



procedure I2X (x 
procedure S2X (x 
procedure D2X (x 
procedure C2X (x 
procedure X2X (x 
{ y := X (ari 


: integer; var y 
: Single; var y 
: Double; var y 
: Comp; var y 
: Extended; var y 
thmetic assignment] 


■ Extended); 

• Extended); 
. Extended); 

• Extended); 
Extended); 

1 } 


procedure X2I (x 
procedure X2S (x 
procedure X2D (x 
procedure XX (x 
{ y := X (ari 


: Extended; var y 
: Extended; var y 
: Extended; var y 
: Extended; var y 
timet ic assignment] 


integer); 
Single); 
Double); 
Comp); 
1 } 



I 

** i.These conversions are not in the Apple // & /// SANE unit 



procedure L2X (x : longint; var y : Extended); 
procedure X2L (x : Extended; var y : longint); 
{ y := X (arithmetic assignment) } 



I 

** Conversions between the niBineric types and the intermediate 
♦* decimal type. 



procedure S2Dec (f : DecForm; x : Single; var y 

procedure D2Dec (f : DecForm; x : Double; var y 

procedure C2Dec (f : DecForm; x -. Comp; var y 

procedure X2Dec (f : DecForm; x : Extended; var y 
{ y := X (according to the format f) } 

procedure Dec2S (x : Decimal; var y : Single); 



Decimal ); 
Decimal ); 
Decimal); 
Decimal); 
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procedure Dec2D (x : Decimal; var y 

procedure Dec2C (x : Decimal; var y 

procedure Dec2X (x : Decimal; var v 
{ y := X } 



Double); 

Ccamp); 

Extended); 



I 

** Conversions between strings and the intermediate decimal type. 
1—} 

procedure Str2Dec (s : DecStr; var index .- integer; 

var d : Decimal ; var Vali (Prefix : boolean ); 

{ d := s^ starting at s[index]; on output index points to 
first character past accepted token; ValidPrefix is 
true if the token, concatenated with the characters 
foil wing it, is a valid prefix of a numeric token. } 

procedure Dec2Str (f : DecForm; d: Decimal; var S: DecStr); 
{ s := d (according to the format f) } 



** Conversions between the ntoeric types and strings. 



procedure S2Str (f : DecForm; x : Single; var y 

procedure D2Str (f .- DecForm; x .- Double; var y 

procedure C2Str (f : DecForm; x : Comp; var y 

procedure X2Str (f : DecForm; x .- Extended; var y 
{ y := X (according to the format f) } 



procedure Str2S (x : DecStr; var y 

procedure Str2D (x : DecStr; var y 

procedure Str2C (x : DecStr; var y 

procedure Str2X (x : DecStr; var y 
{ y := X } 



Single); 
Double); 
Comp); 
Extended); 



I . 

** Niffnerical 'library' procedures and functions. 



procedure RemX 



DecStr); 
DecStr); 
DecStr); 
DecStr); 



•) 



(x : Extended; var y : Extended; 

var quo : integer); 
{ (new y) := (old y) - x * n, where n is the integer closest 
to y/x; n is even in case of tie. 
quo := low order seven bits of integer quotient y/x, 

so that -127 <= quo <= 127. } 
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procedure SqrtX (var x .- Extended); 

{ X := sqrt (x) } 
procedure RintX (var x : Extended); 

I x := rounded to integral value of x } 
procedure NegX (var x : Extended); 

{ X :=-X } 

procedure ftbsX (var x : Extended); 

{ X := |X| } 

procedure CpySgnX (var x : Extended; y -• Extended); 
{ X := X with the sign of y } 

procedure NextS (var x : Single; y : Single); 

procedure NextD (var x : Double; y .- Double); 
procedure NextX (var x : Extended; y : Extended); 
{ X := next representable value from x toward y } 



function 


ClassS 


(X 


: Single; var 


sqn 


: integer) 


: NumClass; 


function 


ClassD 


(X 


: Double; var 


sqn 


: integer) 


: NumClass; 


function 


ClassC 


(X 


: Conip; var 


sgn 


: integer) 


: NigClass; 


function 


ClassX 


(X 


: Extended; var 


sgn 


: integer) 


: NumClass; 


{ sgn 


:= sign 


of 


x (0 for pos^ 1 


for 


neg) } 





procedure ScalbX (n : integer; var y .- Extended); 

{ y := y * 2'^n } 
procedure LogbX (var x : Extended); 

{ returns unbiased exponent of x } 

{ 

** Manipulations of the static numeric state. 



procedure SetRnd (r : RouncDir); 

procedure SetEnv (e : Environ); 

function GetRnd : RouncDir; 

procedure GetEnv (var e : Environ); 

function TestXcp (x : Exception) .- boolean; 

procedure SetXcp (x : Exception; OrtDff .- boolean); 

function TestHlt (x : Exception) -. boolean; 

procedure SetHlt (x : Exception; OnOff : boolean); 
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I 

** ! Lisa and Mac only. 

{ Procedures to Get and Set Extended Rounding Precision are in liathlib 

procedure ProcEntry (var e : Environ); { Procedure entry protocol . } 
procedure ProcExit(e : Environ); { Procedure exit protocol. } 

{ } 

{ ELEliS: Elementary Functions. } 

procedure Log2X (var x .-Extended); 
{ X := log2 (x) } 

procedure LnX (ver x -. Extended); 
{ X := m (x) } 

procedure LnlX (var x : Extended); 
{ X := In (1 + x) } 

procedure Exp2X (var x : Extended); 
{ x := 2''x } 

procedure ExpX (var x : Extended); 
{ X := e"x } 

procedure ExplX (var x : Extended); 
{ x := e"x - 1 } 

procedure Xpwrl (i : inteqer; var x .- Extended); 
{ X := x-^i } 

procedure XpavrY (v : Extended; var x : Extended); 

{ X := X> } ■ 

procedure Compound (r, n : Extended; var x : Extended); 
{ X := (1 + r)^! } 

procedure Annuity (r, n : Extended; var x : Extended); 
{ X := (1 - (1 + r)"-n) / r } 

procedure fttanX (var x : Extended); 
{ X := atan(x) } 
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procedure SinX (var x : Extended); 
{ X := sin(x) } 

procedure CosX (var x : Extended); 
{ x := cos(x) } 

procedure TanX (var x : Extended); 
{ X := tan(x) } 

procedure RandomX (var x : Extended); 
{ X := (7^5 * x) mod (2''31 - 1) } 

{ 



{ Procedures for Lisa and Mac only. } 

function GetHltAddress : longint ; { Returns halt address. } 

procedure SetHlt Address ( Hit Address .- longint ) ; { Sets halt address. } 

procedure InitFPLib ; { Initializes FPLib. } 

function SWC_Environ .- longint ; { Internal use only. } 
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D.4 MathLib 

The intrinsic unit MathLib, contained in the file lOSFPLib, contains 
procedLfl-es in the following areas: 

- Envii-onment Procedtores. 

■ Elementary Functions. 

■ Utility Procedures. 

■ Sorting. 

■ Free-Format Conversion to ASCII. 

■ Correctly Rounded Con-v/ersion between Binary and Decimal. 

■ Financial Analysis. 

■ Zeros of Functions. 

■ Linear Algebra. 

D.4.1 How to Use MefchUb 

MathLib is a Lisa intrinsic unit. Thus it may be conveniently used by Pascal 
programmers. MathLib procedures may also be used by assembly-language 
programmers who observe the Pascal conventions for data structures and 
procedure calls. 

When writing Pascal source code, include a USES statement such as: 

USES FPLib, MathLib ; 

after the program statement in a main program or after the interface 
statement in a unit. If you are also using other units, include FPLib and 
MathLib in the list of units in your one USES statement. They may be listed 
before or after other units you are using, but FPLib must appear in the list 
before MathLib. 

D.4.2 Environment Procedures 

ly^ RoundPrecision = ( ExtPrecision, DblPrecision, RealPrecision) ; 

ProcediDre SetPfecision ( p : RounidPrecision ) ; 

{ Set rounding precision. } 
Function GetPrecision : RoundPrecision ; 

{ Get roundirq precision. } 
Rrocecbire ClearXcps ; { Turn off all exception flags. } 

Procedure ClearHlts ; { Disable all halts. } 

The environmental control procedures in MathLib supplement those in FPLib. 
They work on the global floating-point environment. 

ClearXcps turns off all the exception flags at once. It is faster than the 
equivalent code: 

for e .-= INVALID to IhEXACT do SetXcp( e, FALSE ) ; 

In the same way, ClearHlts disables all the halts at once. 
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The MathLib type RoundPrecision defines the possible settings of the 
rounding precision mode. The procedures SetPrecision and GetPrecision are 
used with RoundPrecision in the same way that SetRnd and GetRnd are used 
with RoundDir. 

Rounding precision is usually used to simulate single-only or double-only 
ai'ithmetic on a system which uses extended-precision expression evaluation. 
Thus to simulate 

Z := X ♦ y ; 

as it would occur in a double-only system, the following suffices: 

savepore := GetPrecision ; { Savepre of type RcMjndPrecision. } 
SetPrecision( DblParecision ) ; 

D2X( X, XX ) ; 

ftddX y, XX ) ; 
X2D( XX, z ) ; 
SetPrecision( sav/eptre ) ; 

In this example the rounding precision affects only the AddD operation. The 
extended result xx is rounded as if the final destination were double 
precision, with inexact, underflow, and overflow signalled accordingly. The 
X2D operation will then raise no further exception. 

D.4.3 Elenrentary Functions 

Const RandNodulus = 2147483647 ; 

{ Prime laodhilus foor randcm number generation = 2^31-1. } 

Function NextRantfom ( lastrandon : longint ) : longint ; 

{ Returns next 'random' lor^int with 1 <= nextrandcm <= 
R^idModhJlu&-l. } 

Procedure ASinX ( var x : Extended ) ; { x := asin(x) } 
Procedure flCosX ( var x : Extended ) ; { x := acos(x) } 

Procedure Sir^ ( var x : Extefided ) ; { x .-= siiili(x) } 
Procedure CoshX ( var x : Extencted ) ; | x := c«^(x) } 
Procedure TanliX ( var x : Extended ) ; { x := tanh(x) } 

Proce<ftire ttusZX ( x, y : Extended ; var z : Exterafed ) ; { z := fi4»s(y4-ix) } 
Procedure ATafi2X( x, y : Extended ; var z : Extended ) ; { z := arg(y+ix) } 

FPLib provides the procedure RandomX which operates on an extended 
argument. A valid argument for RandomX is an integral value between 1 
and 231-2, and RandomX replaces a valid argument with the next such valid 
ai-gument. MathLib provides a more efficient function NextRandom, which 
operates on and returns longints. The following is equivalent to 
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RandomX( x ) for valid arguments x: 

X2L( X, Ix ) ; 

LX := NextRandom ( Ix ) ; 
L2X( Ix, X ) ; 

NextRandom uses integer rather than floating-point arithmetic and thus is 
faster. The result of supplying an invalid argument to NextRandom is 
undefined. 

The constant RandModulus can be used as in either of the following 
examples to produce an array of numbers distributed uniformly strictly 
between and 1: 

L2X( RandModulus^ }<Ran(l1odulus ) ; 

I2X( 1234, r ) ; 

for i := 1 to n do begin 

RandtniX( r ) ; 

t :=r; 

DivX( XRandnodulus, t ) ; 

a[i] := t ; 
end ; 

OR 

L2X( Raraflodulus, ^O^amfflodulus ) ; 

Ir := 1234 ; 

for 1 := 1 to n do begp.n 

It := NextRandofaC Ir ) ; 

L2X( Ir, t ) ; 

DivX( xRandnodulus, t ) ; 

aCi] == t ; 
end ; 

The elementary functions ASinX^ ACosX, SinhX, CoshX, and TanhX provide 
inverse sine and cosine, and hyperbolic sine, cosine, and tangent. Aiguments 
in the interval [-1, +1] are valid for inverse sine and cosine; for these 
arguments, ASinX returns a value in [-pi/2, +pi/2] while ACosX returns a 
value in [+0, +pi]; the NaN for inverse trigonometric functions is returned for 
other arguments. The hyperbolic sine, cosine, and tangent ei-e defined for all 
arguments, but SinhX and CoshX signal overflow for large arguments. 

Abs2X and ATan2X are provided to facilitate coordinate conversion. Abs2x 
computes the square root of the sum of squares of its sirguments; ATan2x 
computes the angle between a point (x, y) and the positive x-axis. ATan2x 
returns a number in [-pi, +pi], even if x or y is zero or infinite. 

To convert from rectangular coordinates (x, y) to polar coordinates (r, t) : 

flbs2X( y, X, r ) ; 
ATan2X( y, x, t ) ; 
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To convert back to rectangular coordinates: 

X := t ; y := t ; 

CosX ( X ) ; SiriX ( y ) ; 
MulX ( r, X ) ; riulX( r, y ) ; 

D.4.4 Utility Procedures 

Type FPJType = ( TFP_byte, TFP_integer, TFP_longint, TFPjCaip, TFP_real, 
TFPJ>oiJble, TFPJExtended ) ; 
{ NurtMsr type nanes for FP.size.} 

Procedure FPjSize ( X: Extended ; var sgn: integer ; var class: NuiClass ; 
var size: FP_Type ) ; 
{ Returns sign bit, class, and size of snallest type that 
iNMjld hold X exactly. } 

Function SignDfX ( x : Extended ) : boolean ; { True if x he^ neg si^i. } 

Functiim FPJIew ( n : Icmgint ) : longint ; 

{ Attenpts to allocate n bytes on heap, returning address. 
Returns ord4(nil) if space not av'ailable. } 

The utility procedures simplify common programming tasks. SignOfX returns 
TRUE if X has negative sign, and FALSE if x has positive sign. Remember 
that zero, infinity, and NaN have sign bits too. The following are equivalent 
but the first is more efficient if only the sign is of interest: 

if SignOfX ( x ) then . . . 

OR 

c := ClassX ( X, sgn ) ; 
if siyi = 1 then ... 

FP_Size tells the smallest storage type that can contain the value of x, and 
as a side benefit rettffns the class of x and its sign in the same format that 
ClassX uses. If x contains an integral value that can be contained in a 
Comp variable, then FP_Size will return TFP_byte, TFP_intege.r, TFPJongint, 
or TFP_comp if the smallest integral container that will contain x is a byte 
-128..+ 127, an integer, a longint, or a comp, respectively. Otherwise FP_Size 
will retLffii TFPj-eal, TFP_double, or TFP_extended if the smallest 
floating-point container that will contain x is real, double, or extended, 
respectively. Thus the size of positive zero is TFP_byte, of negative zero is 
TFP_real, of infinity is TFP_real, of denormal is TFP_extended, and of NaN is 
always one of the floating-point sizes. 
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FP_New is a shortcut way to allocate a number of bytes on the Pascal heap 
without specifying the data structure to be placed there. It is used 
internally in MathLib to implement temporary arrays needed by the sorting 
and linear algebra procedures, but it is also useful for allocating space for 
other dynamic storage structures. The number of bytes to be allocated is 
specified by a longint argument and thus can be as large as desired, although 
the Lisa Pascal heap will rarely have more than about 600000 bytes 
available. If the requested space is available, then FP_New returns the 
address of the first byte of the allocated storage; if not available then 
FP_New returns ord4(nil). For instance, to allocate an array of 10000 double 
precision, do the following.- 

const DaJBLESI2E = 8 ; { 8 = SizeOf (Double) } 

dpa := FP_New( ard4( 10000) ♦ D0UBLESI2E ) ; 
if dpa = ciQrd4(nil) then { eorror } else { ok } 

Assuming the array is to be indexed from to 9999, to access element k: 

type pd = * Double ; 

pd := pointer( dpa + oard4(k) * DOUBLESIZE ) ; 
ak := pd* ; 

Just as in using the built-in Pascal procedure new, appropriate use of mark 
and release allows reuse of heap space: use marKp) just before calling 
FP.Mev,*, and then release(p) when that and any other heap space subsequently 
allocated with new or FP_New is no longer in use. 

D-4.5 Sorting 

Procedure M^th_Soort ( { General procedure to stably sort an arbitrary list.} 
first, last : integer ; { Records first.. last will be sorted. } 

Functicwi Sorted ( i, j : integer ) = boolean ; 

{ User-si^vli^ procedure called by MathJSort to compare order of 
records i arai j. Mteith_sart guarantees first <= i < j <= last. 
Sorted returns true if records i and j are already correctly 
sorted with respect to each other. } 
PTcK^edure Swe^) ( i, j : integ^ ) ; 

{ User-st4>plied procedure called by Math_Sort to swap records i 
and j. Math_sart guarantees first <= i < j <= last. } 
Var error : boolean ) ; { True if sort routine failed due to 

insufficient hdap space a^/ailable. } 
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Math_Sort is a generalized merge sorting procedure. It has no knowledge of 
the structLire of the records being sorted; it obtains the information it needs 
through the user-supplied procedures Sorted and Swap. Math_Sort only calls 
Sorted and Swap with i and j satisfying first < i < j < last. 

Math_Sort contains two phases: sorting and swapping. To sort n records^ the 
number of calls of Sorted is proportional to n*log(n). The number of calls of 
Swap is at most n-1. 

The algorithm is siatJe: If prior to the sort, two records i followed by j are 
correctly ordered with respect to each other, then after the sort, the record 
that was originally at i will still be followed by the record that was 
originally at j. This is true even if Sorted( i, j ) and Sortec^; j, i) are true, as 
might happen if Sorted were implemented by a comparison like 
' key[i] <= ke.y[j] '. 

Internally, Math_Sort. creates and disposes of a temporary array on the Pascal 
heap of size 4 * (last - first + 1) bytes. If there is insufficient heap space 
available then error will be set TRUE and no sorting will be done. 

The following sorting example is based on an array of 1000 records 
containing a primary key, which is a double precision number, and a 
secondary key, which is binary. For this example, records with NaN keys ai'e 
to go to the end of the list. 

type srec = recaordl 

key : Double ; 
subkey : 0..1 ; 

end ; 

var a : array [1..10003 of srec ; 

function srecsorted ( i, j : integer ) ; (* User Sorted function. *) 

var ki, kj : Extenited ; 

tM^gin (* srecsorted *) 
D2X( a[i3.key, ki ) ; 
D2X( a[j].key, kj ) ; 
case RelX( ki, kj ) of 

LT : srecsorted := TRUE ; 

GT : srecsorted := FftUSE ; 

BO : srecsorted := a[i]. subkey <= a[j]. subkey ; 

LflDRD : srecsorted := ClassX( ki, sgn ) <= ClassK( kj, sgn ) ; 
end (♦ case *) ; 
end {* srecsorted *) ; 

procedhire srecs«fap ( i, j : integer ) ; (* User Swap fimction. *) 
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var t : srec ; 
begin (* sxecswap *) 

t := a[i3 ; 

a[i] := a[j] ; 

a[j] := t ; 

end (* srecswap *) ; 
. . (* In tte user's main progran. 



■) 



Hath_So(rt( 1, 1000, sxecsitiartedl, srecswap, etrrtxr ) ; 

if earroar then { not enough heap space } else { sorted OK } 



D-4.6 Free Format Ccmversion to ASCII 



Type Free_FcianBat = record 
liaxSig : integer ; 
SigLFFoTTO, 



Trail_Point, 
IntJEFarni, 

Plus_EFarra : boolean 
end ; 



Procedure FP_Free_flSCII ( 
X : Extended ; 
Width : integer ; 
fom : Free_Fcxniat; 
var s : Ctecstr ) ; 



{ Sipecifi cat ions for free-fans output. } 

I Haximun number of significant digits. } 

{ True if "fixed" style applies tIaxSig to 

significant digits; false if to digits 

after the point. } 

{ True if trailing point should be printed 

for inexact values in "integral" style. } 
{ True if "exponential" style acceptable for 

integral values. } 

{ True if "exponential" style should exhibit 

+ sign for positive exponents. } 



{ Procedure to provide free foonn ASCII output. } 
{ NumiKX to be converted frora binary to ASCII. } 
{ Maximun nuaber of characters in output string.} 
{ Detailed fannat specifications. } 

{ Output destination strir^. If, after call, 
length(s) > Width, then x was inconsistent with 
the constraints Width or MaxSig. } 
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FP_Free_ASCII provides a solution to the following problem: Given a number 
to be displayed in ASCII in a fixed field width, choose an ASCII format that 
displays as much information about the number as possible with as few 
ASCII characters as possible, not exceeding the fixed field width unless 
absolutely necessary. 

Thus the number one should be displayed as '1' and not '1.0' or 'leO'. 
Positive zero should appear as '0' and not 'O.OOOe-0'. Pi, to be displayed in 
columns of width 1, 5, 10, and 15, should appear as '3', '3.142', '3.14159265', 
'3.1415926535898'. -0.00001 should appear as '-1E-5' unless Width >=7, in 
which case '-.00001' should appear. 

The following special cases are formatted strictly according to Width: 

For positive zero, s := '0'; for negative zero, s := '-0' unless Width <= 1, in 
which case s .-= '0'. 

For positive infinity, s := 'Inf; for negative infinity, s := '-Inf'. 

For NaNs, s will have the value that XZStr would return, unless that would 
exceed Width; then s -.= 'NaN' or '-NaN' depending on the sign bit, unless 
Width <= 3; then s := 'NaN' regardless of sign. 

The essential method for formatting normal numbers is to first attempt a 
representation with integral format, then with a fixed decimal point format, 
and then with an exponential format with a minimal number of decimal 
digits in the exponent. (FORTRAN programmers are familiar with these as I, 
F, and E formats, respectively.) At each stage, a representation is rejected 
if it would require more than Width ASCII characters to represent the 
number according to the specifications in the Free_Format record. 

The number of significant digits nevei- exceeds 19 and may be further limited 
by MaxSig. 

Integral format is attempted only if x contains a value that would fit 
exactly in a Comp. The integral format, of ten billion is 10000000000, but 
3.14, not being an integral value, is not displayed in integral format. When 
the Free_Format field Int_EForm is true, then numbers like ten billion are 
shortened to IE 10 by converting three or more trailing zeros to an E and 
exponent. 

A string in fixed decimal point format might look like '123.456' or 
'.00000000000234565'. MaxSig specifies the maximum number of digits that 
will be displayed. Sig_FForm determines how MaxSig is applied. If 
Sig_FForm is TRUE then there will be no more than MaxSig significant 
digits. Significant digits are counted from the first nonzero digit to the last 
nonzero digit. Thus 123456000000., 123.456, and .0000000000123456 all have 
six significant digits. If Sig_FForm is FALSE then there will be no more 
than MaxSig digits s^er the point. Thus 10000000000000.123456, .123456, and 
.000001 all have six digits after the point. 
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After rounding to the specified number of decinnal digits, which may be 
reduced to fit in Width, trailing zeros after the point are ignored. Thus if 
the number, rounded to six digits after the point, was 123.4560CX), the last 
three zeros would be deleted. Sometimes all the digits after the point might 
be removed, as in the case of 123.000000, which would be truncated to '123.'. 
Whether a trailing point is retained is determined by the Free_Format field 
TraiLPoint: if TRUE, then s := '123.'; if FALSE, s := '123'. Note that the 
original value of x in this example could not have been 123 exactly; x would 
then have been displayed as '123' in integral format. Instead it might have 
been 123.0000000000001 before rounding to six digits after the point. 

Finally exponential format is tried. MaxSig specifies the maximum number 
of significant digits to be displayed. If x is ten billion, then the exponential 
display will depend on the specification as follows.- 

Trail_Point: PlusJEForru: String: 



False False lElO 

True False I.EIO 

False True lE+lO 

True True I.E+IO 

When a single- or double-precision number is converted to extended and then 
converted to ASCII in free format with no more than 18 significant digits, 
then the ASCII string will satisfy the requirements of the IEEE Standard. But 
a free form string that, for instance, displays 12 digits in exponential 
format, m^ differ by one in the last digit from the string that would be 
obtained by calling S2Str or D2Str with form = FLOATDECIMAL and digits = 
12. Both strings satisfy the IEEE Standard; a difference may only arise in 
the extreme exponent cases for which the Standard allows more than one 
possible result for conversion from binary to decimal. 

Denormal x is always represented in exponential form with four exponent 
digits. 

In LisaCalc, the default formatting conventions are MaxSig = 14, Trail_point 
= FALSE, Int_EForm = FALSE, Plus_EForm = FALSE. SigLFForm is set 
FALSE for numbers less than one in magnitude, and TRUE otherwise. 

Examples: 

MaxSig = 19 

Sig_FForm = TRUE 

Trail Point = TRLE 

Int_EForm = TRUE 

Plus EForm = FALSE 
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Input = 1234567890.0123456789 
Width 



>= 20 

19 

18 

17 

16 

15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

<= 4 



String 

'1234567890.012345678' 

'1234567890.01234568' 

'1234567890.0123457' 

'1234567890.012346' 

'1234567890.01235' 

'1234567890.0123' 

'1234567890.012' 

'1234567890.01' 

'1234567890.' 

'1234567890.' 

'1.23456^9' 

'1.23457E9' 

'1.2346E9' 

'1.235E9' 

'1.23E9' 

'1.2E9' 

'1.E9' 



Input = .00001234 

>= 25 
23.. 24 

8.. 22 

7 

6 
<= 5 



.00001233999999999999999 ' 

1 . 233999999999999999E-5 ' 

1.234E-5' 

1.23E-5' 

1.2E-5' 

l.E-5' 



Input = -6.023e-23 

>= 25 
10.. 24 

9 

8 
<= 7 



' -6 .022999999999999999E-23 ' 

'-6.023E~23' 

'-6.02E-23' 

'-6.E-23' 

'-6.E-23' 
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D.4.7 Conrectly Rounded Conversion Between Binary end Decimal 

Const LSigPigLen = 30 ; { Length of significand string. } 

Type Lon^igPig = string [LSigPigLen] ; 

Lon^ecinal = record 

sgn : 0..1 ; 
exp : inte^ ; 
sig : LongiSi^ig ; 
end ; 

Procedure X2LDec ( f : DecFom ; x : Extencted ; var y : LongPecinal ); 
{ Converts x to y, cotrrectly rounded according to f . } 

Procedure LDec2X ( prec- RmjndPrecision; X: Lon^Decinal; var y: Extended ); 
{ Converts x to y, coarrectly rounded according to prec. } 

The procedLffes X2LDec and LDec2X correspond to X2Dec and Dec2X^ and 
work similarly, only more accurately and much more slowly. The IEEE 
Standard does not require correctly rounded conversion for single- and 
double-precision numbers for extremely large and small exponents, and does 
not specify conversion at all for extended-precision numbers. The results 
returned by Dec2S, S2Dec, Dec2D, and D2Dec may differ by one unit in the 
least significant bit or digit from the correctly rounded results, while the 
results returned by Dec2X and X2Dec may differ by more than one unit from 
the correctly rounded results. 

The correctly rounded conversion routines accept or produce up to 30 decimal 
digits. X2LDec produces correctly rounded LongDecimal records according to 
its DecForm parameter. To obtain correctly rounded results from Single, 
Double, or Extended arguments, use one of the sequences.- 

S2X( S, X ) ; 
X2LDec( f , X, y ) ; 

OR 

D2X( d, X ) ; 
X2LDec( f, X, y ) ; 

OR 

X2LDec( f, X, y ) ; 

LDec2X rounds correctly according to its RoundPrecision parameter. To 
obtain correctly rounded single, double, or extended results, use one of the 
sequences: 
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LDec2X( REALPRECISION, x^ y ) ; 
X2S( y, s ) ; 



OR 



LJ)ec2X( 
X2D( y. 


DBLPRECISIQN^ 


OR 




LDec2X( 


EXII^M-niSIGN^ 



X, y ) 



X, y ) ; 

No correctly rounded conversions to DecStr strings are provided^ but the 
routines Str2Dec and Dec2Str may be tricked to apply to LongDecinr»al 
arguments. To convert a DecStr x with no more than 19 significant digits to 
a correctly rounded Extended y, do.- 

var t : Decinal ; 

pd : * LongPecinal ; 

index := 1 ; 

Str2Dec( x, index, t, ValicPrefix ) ; 

pd := pointer ( CKrd4( it) ) ; 

LDec2X( EXTPREEISION, pd", y ) ; 

and to convert an Extended x to a string y correctly, dO: 

var t : Lcvi^cinial ; 
pd : "^ Decinal ; 

X2LDec( f , X, t ) ; 

pd := pointer ( ord4( it) ) ; 

Dec2Str ( f, pd*, y ) ; 

X2LDec sets the inexact flag appropriately. LDec2X sets the inexact, 
underflow, and o-verflow flags appropriately. 

The time required to convert correctly rounded is proportional to the square 
of the exponent. The most extreme double precision numbers take a few 
seconds, but extendeds with very large or small exponents require up to 
twenty minutes. Thus these routines are too slow to L^e habitually for 
converting the full range of extended-precision numbers; use these routines 
for applications such as obtaining the best possible approximations to 
tabulated values of mathematical constants such as pi or e. 

D.4.8 Financial Analysis 

Procedure FinJ^ ( { Co^Hite net valt» of series of paiyBents. ] 

first, { First paynent period. } 

last, { Last paR^ment pieriod. } 
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net : integer ; { Period at «^ich net value is to be 

conputed; need not be betvfeen first and 
last. } 
late : Extended ; { Peariodic interest rate. } 
var Npv : Exteraled ; { Net |»^ent value. } 
Procedure payment ( i : integer ; var put .- Extencted ) 

{ User-supplied procedure to provide pnt, the payiMMnt at 

period i. } 
{ Fin_Npv guarantees first <= i <= last. } 
); 

Procedure Fin_Return ( { Analyze series of paynents for external or 

internal rate of return. Discounting by 
external rates may be specified for positive or 
rK»gative payments or both or neit^war. Standard 
internal rate of return is (Stained by 
specifying, for exanple, ne^eriod, fmsperiod := 
first-1. A conservative external rate of return 
is obtained by considerir^ negative payments as 
out from the investor^ FM>sitive payments as in 
to the investor, and specifying: 

negmeriod := first ; 

posperiod := last ; 

negrate := guaranteed safe rate of return ; 

posrate := expected average portfolio 

reinvestment rate of return. } 

first, { Initial payment period. } 

last : integer ; { Final payment iraoriod. } 

ne^ieriod, po^Msriod : integer ; 

{ Periods to which n^ative or positive parents 
are to be discounted; if < first or > last then 
correspcMnding ^raynents are rKit discounted. } 
negrate, posrate .- Extemted ; 

{ Discount rates for negative and prasitive payments 
respc»:tively; ignored if corresfKHiding period 
dc»s not satisfy first <= ...period <= last. } 
var ncs : integer ; { Error code = numtMsr of changes of sign 

aniong adjusted payiKintS; on normal return 
res = l.ncs = -2 if an inf or NaN 
paymott was sufiplied. } 
var ret : Extended ; { Rate of return: if ncs = 1 then ret will 

contain the single real root > -1; if ncs 
> 1 is odd, then ret will contain sane 
real root > -1; if ncs > 1 is even ret 
may ccmtain a real root > -1; otterwise 
ret will contain NaN. } 
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Procedure pajj^ent ( i : integer ; var pnt : Extended ) 
{ User-supplied prcu^edure to provide pnt, 

the psR/nuent at period i. } 
{ FinJNIpv guarsntees first <= i <= last. } 

); 



Fin_Npv is used to calculate the time value of a series of payments. 
Typically, a series of payments, to occur at times 1 through n, is to be 
discounted to a net present value at time using a fixed discount rate r. 
The contribution of the first payment pi will thus be pl/(l+r); the next will 
be p2/(l+r)"2; the last pn/(l+r)"n. For this typical problem, first=l, last=n, 
net=0, and rate=r. 

For a fixed series of payments, Vi, the net value at time i, and Vj, the net 
value at time j, are related by: 

Vi = Vj * ccmpound( rate, i-j). 

So if the net value is zero at one time, it will be zero at any other time. 

Note that discount rates <= -1 ere meaningless from a financial point, of 
view. 

Often a transaction involving payments between two parties at different 
times is regarded as fair if the net discounted value of the payment series is 
zero at the agreed upon discount rate. Alternately, given a series of 
payments regarded as fair, we might interpret the effective interest rate as 
one making the net value of the payments zero. Note that roundoff error 
may prevent the net value from ever being exactly zero. Furthermore, the 
net value can not be zero if any payment is infinite or a NaN, or if all the 
nonzero payments have the same sign. 

Fin_Return is designed to solve the problem mentioned above: given a series 
of payments, what- discount rate would result in a net value of zero? This is 
the conventional form of the Internal Rate of Return (IRR) problem. In this 
form, it should be obvious that there will not always be a rate corresponding 
to every series of payments: if any payment is infinite or NaN, or if all the 
payments have the same sign, then no discount rate can ever make the net 
value zero. It turns out in other cases that there may be no such rate or 
there may be several rates with equally valid right to be called "internal rate 
of return." Modified methods for solving such problems will be discussed 
later. 

To obtain a conventional internal rate of return, in the Fin_Return calling 
sequence set negperiod and posperiod to, for instance, first-1 or last+1. Then 
after the call, the output parameter ncs returns a code to aid in 
interpretation of the result ret. 

Fin_Return will not. attempt to compute an internal rate of return if any 
payment is infinite or NaN or if all payments are zero or all nonzero 
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payments have the same sign. Fin_Return will return a NaN with code 
NaNIRR in these cases. Ncs = -2 if any payment was infinite or NaN; 
ncs = in the other cases mentioned. 

If ncs >= 1 then its value is the number of changes of sign in the payment 
series. A change of sign occurs whenever a nonzero payment has different 
sign from the previous nonzero payment. Thus, in the sequence: 

10,8,7,0,13,0,-0,1,0,-1,0,0,-7,0 

there is exactly one change of sign, between +1 and -1. The zero payments 
ai^e ignored in computing changes of sign. 

The number of changes of sign is important: if it is an odd number then the 
internal rate of return problem has one or more solutions; if it is an even 
number >= 2 then the internal reite of return problem may have one or more 
solution. Generally, the number of real solutions > -1 is the number of 
changes of sign or is less than that number by an even integer. So a series 
with three changes of sign has three or one internal rates of return while a 
series with four changes of sign has four, two, or none. 

Fin_Return always computes an internal rate of return if ncs is odd. If ncs 
= 1 then assuredly ret contains the only internal rate of return. If ncs >= 3 
then ret contains an internal rate of return but there may be others and 
there is no assurance that the value in ret is appropriate in the user's 
context. 

If ncs >= 2 is even, Fin_Return will search for an internal rate of return but 
will soon give up if it can't find any. In the latter case ret will be NaNIRR. 
There is no way to distinguish the cases in which no internal rate of return 
exists from those in which Fin_Return is unable to find one. If ret is not a 
NaN then it is a valid rate of return but there is at least one other that may 
be equally valid. 

When there are two or more changes of sign the interpretation of the 
internal rate of return is evidently not a simple matter. One may plot the 
net present value of a series as a function of discount rate. Points where 
the graph crosses the x-axis are internal rates of return. Perhaps one of 
these points will be obviously suitable. 

Another approach to rate of retuin is to simplify the series of payments until 
there is only one change of sign. For instance, if there are only two 
payments of different sign. Pi at time i and Pj at time j, then the internal 
rate of return r is defined by the equation: 

(l+r)J-i = -PJ/Pi 

which should be solved by the formula: 

r := expl( lnl( -(Pi-»Pj)/Pi )/(j-i) ); 

Various methods based on this approach are called adjusted, modified, 
financial management, or external rate of return. A subseries such as all the 
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positive payments is replaced by its discounted value at some time, using an 
externally defined discount rate. If that positive subseries is replaced by a 
single positive payment, either before or after all the negative payments, 
then there will be exactly one change of sign and exactly one internal rate 
of return. Either the positive subseries or the negative subseries or both 
may be discounted; the same external discount rate may be applied to both, 
or different ones may be applied to the negative and positive subseries. 

As an example, consider the following series of payments: 

-3, -2, 2, -1, 1 IRR = -.325 

It has three sign changes, so there are either one or tlrree internal rates of 
return. We might discount all the negative payments to the beginning, using 
a discount rate of 0.5, to get a different series: 

-43/9, 0, 2, 0, 1 IRR = -.156 

or we might discount all the positive payments to the end, using a discount 
rate of 0.75, to get: 

-3, -2, 0, -1, 57/8 IRR = +.055 

or we might do both to get- 

-43/9, 0, 0, 0, 57/8. IRR = +.100 

Each of these three series has a unique internal rate of return, but these 
rates differ according to the choices made to simplify the problem. 

Fin_Return allows for all these possibilities. To discount the subseries of 
negative payments to a single time between first and last, simply specify 
negperiod to be that time and specify a discount rate in negrate. Similarly, 
posperiod and posrate may be used to discount the subseries of positive 
payments. 

The following code fragments correspond to the previous examples: 

var 

p : aarray[l..ni] of real; 

procedure paviient(i: integer; var pmt: Extended); 
begin 

S2X(p[iL pint); 
erHi; 



begiin 
S2X(0-5, negrate); S2X(0-75, posrate); 

FinJReturn( 1, n, 0, n+l, negrate, posrate, ncs„ retirr, paynent); 
if ncs >= 1 then if not(ClassX(retiix,sgn) in [ QNflN^SNflN ] ) then 
{ retirr is a conventional internal rate of return. } ... 
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Fin_Retiim(l, n, 1, m-l, negrate^ posxate, ncs, xetneg, paynerit); 
if ncs >= 1 then { retneg is a return rate based on discountir^ 
negative ps^nents to tte beginning. } ... 

FinJRetiim(l, n, 0, n, negrate^ posrate, ncs, retpos, peynent); 
if ncs >= 1 then { retpos is a return rate based on discoumtin^ 
positive pcvytHM^its to the end. } ... 

FinJRetum(l, n, 1, n, negrate, posrate, ircs, retx, paynent); 
if ncs >= 1 tten { retx is a return rate based on discounting all 
paynents to the beginning or end. } ... 
end; 

LisaCalc adopts the convention that negative payments are discounted to the 
first time period, and positive payments are discounted to the last time 
period. If only one discount rate is specified, it is used for both negrate and 
posrate. 

A common type of complex investment involves several payments in followed 
by several payments out. Even though with only one sign change thei'e is a 
unique internal rate of return, it may not be meardngful since it does not 
reflect external conditions. A frequent basis for analysis is to require that 
at the beginning, sufficient funds must be on hand to be able to guarantee 
all payments in. So all the payments in are discounted to the first period 
using a "safe" guaranteed rate of return such as the return on a conventional 
savings account. Payments out, on the other hand, are to be reinvested at 
another rate which is probably higher than the safe rate. This rate is 
sometimes called the "portfolio" or "reinvestment" rate and represents the 
average return of the investment portfolio. These externally defined safe and 
reinvestment rates modify the rate of return of the investment. 

When analyzing complex investments, remember that the computed results 
are no better than the assumptions from which they were developed. In 
particular, measures of rate of return do not reflect the risk that some of 
the payments might not. occur as expected. 

D.4.9 Zero of a Nonlinear FwKtion 

Procedure ifethJSolve ( { Computes zero of furKtion. } 

estl„ est2 : Extended ; {A priori estimates of zero. } 
var res : Extended ; { f (res) may = or NaN or its sign mav 

differ from or» of its neigNtors or it 
na/ merely be the x «fith minimal 
abs(f(x)) among those x sampled by 
MathJ^lve. The user must decide the 
significance of the result res. } 
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porocedure f ( x : Extended ; vatr fx : Extended ) 

{ User-siqiplied proceAire to evaluate fx = f(x). } 

Math_Solve is used to find a zero z of a nonlinear function f(x), that is^ a 
place where f(z) = 0. Z is also called a root of the equation f(x) = 0. 

The user nnust specify the function f which should be at least piecewise 
continuous; the better the function, the better Math_Solve can perform. The 
user may also specify one or two starting guesses. The user may supply 
NaNs as guesses; then Math_Solve will generate its own guesses which 
usually will not be as efficient as those the user might have supplied. Zero 
finding is tricky enough with good guesses, so the user should supply the best 
information he can. 

Internally, Math_Solve has two main phases: the search for a sign change 
interval and the refinement of such an interval. A sign change interval is an 
interval for which the values of f at the endpoints have different signs. If 
the function is continuous it will have a zero in the interval; if l/f(x) is 
continuous then f will have a pole in the interval. Thus finding a sign 
change interval is critical. That interval is sought Lsing a secant method 
whenever that is productive, and a paiabolic method otherwise. After the 
sign change interval is found, the secant method is used unless bisection is 
faster. If no sign change interval is found, Math_Solve eventually gives up, 
leaving in res the point at which the sampled function's magnitude was 
minimal. 

Only the user can determine the ultimate significance of res. That's because 
nonlinear functions display a variety of complicated behaviors that can't be 
handled equally efficiently by one subroutine. Many functions such as f(x) = 
1 + X * X have no real zeros while others may hide their zeros where 
Math_Solve can not find them. 

To interpret res, compute f(res). Seldom do we find the happy circumstance 
that f(res) is without generating any exceptions. If inexact, underflow, or 
other exceptions v/ere signalled then the user must decide whether to ignore 
them or to subject res to the further tests described below. If f(res) is a 
NaN then Math_Solve has wandered outside the domain of validity of f. The 
user might want to extend the domain of f and try again. Sometimes such 
extension is trivial, se in the case of a removable discontinuity. 

Suppose f(x) were defined as siitx)/X; then at x = its value is a NaN, and if 
Math_Solve were to look there it would stop with res = 0. Remove this 
discontinuity by defining f(x) by 

if X = then f(x) := 1 else f(x) := sin(x)/x; 

A tougher case is a function like f(x) = sqrt(x) - 2 ; if Math_Solve happens to 
look at x < it v<'ill stop on a NaN. In this case, extend this definition of 
f(x) leftward: 
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if X <= then f(x) := -2 else f(x) := sqrt(x) - 2; 

Many such domain problems can be avoided if the starting guesses are 
sufficiently close to the desired zero. 

Suppose now that f(res) is a nonzero number or infinite. One possibility is 
that res is actually a zero of f but that the computed value f(res) is nonzero 
because of roundoff. Another possibility is that the true zero of f does not 
lie at a machine representable number but lies between res and one of its 
adjacent machine representable numbers. A third possibility is that res lies 
at or near a pole rather than a zero of f . Let's consider these cases in turn. 

Often it is possible to compute an analytical error bound ef(x) for a function 
f(x) that indicates a bound on the roundoff error in the function at x. Then a 
reasonable approach is to evaluate f(res) and ef(res) and accept res as an 
approximate zero of f if the error bound dominates the function value, that 
is, abs(f(res)) <= ab^ef(res)). 

Books on rounding error analysis provide examples for constructing analytical 
formulas for error bounds. Another possibility is to use interval arithmetic 
to obtain computational error bounds. The directed rounding modes of IEEE 
arithmetic are helpful in implementing interval arithmetic. 

A simpler alternative that suffices in many cases is simply to evaluate f(res) 
in each of the four IEEE rounding directions. If f is typical^ then f(res) will 
be different in each rounding direction. If all four values are nonzero with 
the same sign, it is usually safe to assume that the true value of f(res) is 
not 0. If one of the four values is or if the signs vary, then the true value 
of f(res) may well be and res may be taken to be an approximate zero of f. 
Furthermore, it often suffices to compute f{res) only in upward and downward 
directions- 
Turning now to the case that the true zero of f is not a machine 
representable number, we may evaluate f at both of res's neighbors. If the 
sign of f at a neighbor differs from the sign of f(res), then f must have 
either a zero or a pole between res and its neighbor. On an interval in 
which f changes sign, it's not possible to distinguish zeros from poles. Other 
knowledge of the function, such as a bound on a derivative, may be helpful if 
this issue is in doubt. 

If f is known to have a pole in the region of interest, it may be useful to 
remove the pole analytically before calling Math_Solve. For example, instead 
of solving ftx) = 3 - 1/x, solve f{x) = 3x - 1 to avoid the pole at zero. But 
beware of introducing spurious zeros this way. 

If none of the above produces an indication of a zero at or near res, then it 
may be that res is merely that point at which abs(f(x3) was minimized among 
these X sampled by Math_Solve. Since many functions do not have real 
zeros, Math_Solve will eventually give up searching if for each point it tries, 
f has the same sign and there is no significant decrease in the magnitude of 
f. If Math_Solve ever finds two points for which f has different signs, then 
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it will persist in searching for a solution until it finds a point x where f(x) is 
or NaN; failing that, the sign change interval will be reduced in size until 
the endpoints are adjacent machine representable numbers. But if the 
function value seems to vanish between two such numbers, then it makes 
sense to accept one of them as a reasonable approximation of the zero. 

It must be emphasized that at best Math_Solve will find a zero of the 
function defined by the pKrocedure f, which may not be the same function the 
user had in mind when he wrote that procedure. Because one function may 
have many mathematically equivalent expressions, it is the user's 
responsibility to find an expression that will not produce gratuitously wrong 
results in the presence of roundoff. Two examples of helpful principles.- 
Avoid or minimize rounding error when possible (e.g., x/10 instead of 0.1* x), 
and cancel early rather than late (e.g., (x+y)*(x-y) rather than x**2 - y**2). 

The following example is intended to find a zero of a polynomial function 

|d(x) = Co * x" + Ci * xf^i + ... 4 Cn-i * X + Cn 

Note that the function is evaluated in extended precision using Horner's 
method of nested multiplications and additions, and the Math_Solve result r 
is evaluated according to the guidelines discussed above: 

const n = { degree of |H)lyncmial >= } ; 
var c : aiTsy [ 0..n ] of real ; 

procedure ii^val ( x : Extended ; vaor px : Extended ) ; 

var i : integer ; 

begin { peval } 
S2X( c[0], px ) ; 

for i :== 1 to n do begin { px := px * x -i- ci } 
«ulX( X, px ) ; 
AddS( c[i3, px ) ; 
end { px := px • X + ci }; 
end { peval | ; 



l1ath_Solve( gl, g2, r, peval ) ; 

ClearXcps ; 

fr := peval(T) ; 

If ClassX(fr,sgri) in [Onan, Snan] then 

{extend function fknain and try again} 
else if (ClassX(fr,sgn) = 2ERD) and { no exceptions } then 

{ accept T as zero } 
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else begin 
SetRnd( DOMNWflRD ) ; 
fd := peval(r) ; 
SetRnd( UPWffiD ) ; 
fu := peval(r) ; 
SetRnd( TOCflREST ) ; 
if Sigrt)fX( fd ) <> SignOfX( fu ) then 

{ accept T as zero } 
else begin 
left := NextX( r, neginf ); {neginf contains negative infinity} 
right := NextX( r, posinf ); {posinf contains positive infinity} 
fleft := peval(left) ; 
fright := peval (right) ; 
if (SignOfX( fleft ) <> SignOfX( fr ) ) 
or (SignDfX( fright) <> SignDfX( fr ) ) then 

{ accept T as a zero } 
else { no zearo «#as found } 
end ; 
emf ; 



D.4.10 Linear Algebra 

The linear algebra routines in MathLib solve comnnon algebraic and 
statistical problems using methods that are independent of the storage 
formats of vectors and matrices. Prior to discussing specific routines we 
shall review relevant sepects of linear algebra. 

D.4.10.1 Vectors w»d Linear TransTormations 

Linear algebra is concerned with elements in vector spaces atid the class of 
linear transformations upon them. If that sounds too abstract, think about, 
this specific example: The vector space is the set of points In a graphics 
v,*indow, forming a picture. One point, the origin, is special; often it is one 
of the corners. Typical linear transformations include the identity 
transformation, which does nothing, scaling transformations, which act like a 
zoom lens to magnify or reduce the picture, and rotations, which rotate the 
picture by a fixed angle relative to the origin. It is possible to combine 
linear transformations to create new ones. 

The simplest way to understand the effect of a linear transformation in two 
dimensiotTS is to consider what it does to the unit circle, which is a circle of 
radius one around the origin. The identity transformation leaves the circle 
unchanged; scaling transformations make the circle bigger or smaller; 
rotations leave the unit circle seemingly unchanged, although circles centered 
elsewhere are rotated as a whole. The unit sphere is the three-dimensional 
counterpart to the unit circle. 

Most linear transformations can be inverted. For instance, a scaling 
transformation that magnifies by two can be in-v/erted by the inverse 
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transformation: a scaling transformation that reduces lay two. A 45-clegree 
clockwise rotation can be inverted by a rotation of 45 degrees 
counter-clockwise. 

Transformations that have inverses are called nonsingular; transformations 
without inverses are called singular. To understand singularity, consider the 
cases of ordinary multiplication and division of numbers. The transformation 
"multiply by x", as in z := x * y, is nonsingular unless x = 0. The inverse 
transformation "divide by x"., as in y := z / x, does not exist when x = 0. 
We could define a "pseudo-inverse" transformation: 

if X = then y := else y := z/x ; 

which exists for any x, but we would not expect to recover the original value 
of y unless by luck it were 0. 

Two-dimensional linear transformations can only map the unit circle In 
certain ways. Nonsingular transformations map the unit circle into a circle 
or an ellipse. Singular transformations map the unit circle into a line 
segment or point. There are no other possibilities. A singular linear 
transformation that maps the unit circle to a line segment is not one-to-one; 
it maps more than one point in the unit circle to the same point on the line 
segment. Such a transformation has no inverse because a point on the line 
segment may h&^e come from more than one point on the unit circle, and 
there's no way to tell from which it came. However, pseudo-inv.'erses have 
been defined which make somewhat arbitrary choice^; all linear 
transformations h»ye pseudo-inverses. 

D.4-10.2 Transformations Between Spaces of Different Dinrension 

Transformations ma?/ be defined which map elements of one vector space 
into elements of another. For instance, a painting of a tlTi'ee-dimemional 
scene is based on aitistic perspective convention "for mapping three 
dimensions into two. 

Linear transformations that map vectors from two dimensions to three can at 
best map the unit circle into a two-dimensional object in the 
three-dimensional space. Transformations from three dimensions to two map 
the unit sphere into at most a two-dimensional object, of course. Generally 
speaking, a transformation that maps the unit circle or sphere into an object 
of the maximum possible dimensionality is said to be of full rank. 
Otherwise it is said to be rank-deficient. When the two spaces are of the 
same dimension, then "full rank" is the same as "nonsingular" and 
"rank-deficient" is the same as "singular." 

D.4.10.3 Arrays and Matrices 

Programming languages deal with arrays of numbers rather than elements of 
a vector space and transformations upon them. Arrays of numbers can have 
any meajiing that the progi^ammer wishes to assign, but conventionally 
vectors are represented by an array with one dimension. Thus an element of 
a two-dimensional vector space might be declaimed as 
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u : array [1--2] of real ; 

where u[l) is the first coordinate, along the x axis, and u[2] is the second 
coordinate, along the y axis, of a point in a two-dimensional space. The size 
of a vector is measured by its Euclidean length, which is the square root of 
the sum of the squares of its elements: 

lengthu := sc|rt( sqr(u[l]) + sqr(u[2]) ) ; 

Linear transformations mapping n-dimensional spaces to m-dimensional 
spaces are conveniently declared as 

a : array [l..n, l..n ] of real ; 

The following discussion uses the term "matrix" to refer to an array 
representing a single linear transformation. The individual components of a 
matrix A depend on the linear transformation that A represents. 

In general, the components of an array representing a two-dimensional linear 
transformation can be determined by examining the effect of the 
transformation on the unit vectors El and E2 corresponding to the 
coordinates (1,0) and (0,1). The first column of A contains the coordinates of 
the result of applying the transformation to El and the second column 
contains the coordinates corresponding to E2. 

In two dimensions, to represent the identity transformation: 

f or i := 1 to 2 do for j := 1 to 2 do 
if i=j then a[i, j] := 1 else a[i^ j] := ; 

while to represent a three times magnification: 

f oar i := 1 to 2 do for j := 1 to 2 do 
if i=j then a[i, j] := 3 else a[i, j] -.= ; 

and to represent a rotation through angle t: 

a[l,l] := cos(t) ; a[l,2] :=+sin(t) ; 
a[2,l] :=-sin(t) ; a[2,2l := cos(t) ; 

One singular transformation is the zero transformation which maps everything 
to the origin: 

for i := 1 to 2 do for j := 1 to 2 do 

Another singular transformation maps arv vector vertically onto the x-axiS: 
for i := 1 to 2 do for j x= 1 to 2 do 

a[l,l3 := 1; 

It maps the unit circle into a line segment on the x-axis. 

Sometimes it is convenient to think of a two-dimensional array [l..m, l-.n], 
not as a transformation from an n-dimensional vector space to an 
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m-dimensional vector space, but as a collection of n distinct vectors of 
dimension m. For instance, a triangle is defined by specifying its three 
vertices, so an array of three columns may be used to represent a triangle. 

With the conventions for vectors and trsmsformations outlined above, there 
are operations for applying transformations to one or more vectors, 
composing transformations, finding the vector that would be transformed to a 
given one^ and computing inverse and pseudo-inverse transformations. 

Composing Trsfisf ormafcions 

To represent a transformation C which first performs A, then performs B, 
multiply the matrix B times the matrix A; in mathematical notation, C := B 
* A. In Pascal you could write 

vaor 

aj, b, c : array [l..n, l..n] of real ; 

foor i :« 1 to n do for j :« 1 to n cto begin 

t :=0; 

for k := 1 to n do t :» t -i- b[i,k]*a[k, j] ; 

C[i,j] := t ; 

end ; 

although the matrix multiplication routine in MathLib is better. If you ever 
wondered why the textbook definition of matrix multiplication is so 
complicated, it is to insure that transformations can be combined by 
multiplying their matrices in this way. Matrix multiplication only works 
when the second dimension of B is the same as the first dimension of A, 
because it only makes sense to compose two such transformations when the 
result space of A is the same as the operand space of B. 

To apply a transformation represented by an array A to a vector X, simply 
multiply them together to get the transformed vector B: 

B := ft * X 

Note that X might represent one or more vectors depending on the number of 
columns of X. 

Linear Equat-ions 

The assignment B:=A*X computes B, given A and X. The inverse problem, to 
compute X, given A and B, is usually called "solving a system of linear 
equations." The dimensions of B, A, and X must conform so that A and X 
could be multiplied to get B. If A is square and nonsingular, there will 
always be a unique X satisfying B=A*X. 

MathLib procedures find X directly from B and A. Another way to find X is 
to find P, the inverse transformation of A, and apply it to B: 

X := P * B 
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But computing P explicitly is always slower and less accurate than computing 
X directly from B and A. 

Linear Least Sq^jares 

The equation B=A*X sometimes has solutions X even when A is singular or 
not square. Sometimes there is more than one such X, at other times there 
is none. All these cases can be generalized as the "linear least squares" 
problem: Given B and A, find an X that minimizes the length of the residual 
R:=B-A*X. Such an X always exists; X will be unique if and only if Y=0 is 
the unique solution of the equation 0=A*Y. 

Cleaiiy X solves the linear equation problem B=A*X if and only if R:=B-A*X 
is zero. Therefore, MathLib provides just one set of procedures to solve the 
linear least squares problem; these procedures can also be used to solve 
linear equations. A solution X is always computed directly from B and A; if 
there is more than one solution X, MathLib returns an X whose length is 
small, but not necessarily minimal among all X minimizing the length of R. 

Only square nonsingular matrices A have inverses, but every matrix A has a 
pseudo-inverse P, which may be applied to B to compute X: 

X := P * B 

But computing P explicitly is always slower and less accurate than computing 
X directly from B and A. 

An even more inaccurate method for obtaining X is to solve the linear 
equation system: 

using A""^, the transpose of A. 

Avoid methods that require P or AT*A rather than A; they are inaccurate, or 
slow, or both. 

Existence 

MathLib always computes an x to solve a linear least squares problem. How 
can you tell whether that x is also a solution of the system of linear 
equations B=A*X? 

That depends on the shape of A. If A has at least as many columns as rows, 
end A is of full rank, then x would satisfy, in the absence of rounding 
errors, B=A*X. Fullness of rank is indicated by a condition number greater 
than zero, discussed in Section D.4.10.4. 

If A has more rows than columns or is rank deficient, then it will be 
necessary to actually compute the residual R:=B-A*X to see if it is zero or 
negligible compared to B. 

Uniqt^ness 

MathLib always computes some X, even when the linear equation system 
B=A*X has zero, one, or many solutions. The multiplicity of solutions may 
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be seen even for b=a*x where b, a, and x are real numbers. This equation 
has a unique solution x=b/a if a*0. But if a=0, then b determines the number 
of solutions. When a=0 and b=0, any value of x is a solution; when a=0 and 
b*0^ no value of x is a solution. 

But the related problem "minimize | b - ax |" always has at least one 
solution x. When a=0, then MathLib chooses the solution x=0, regardless of 
b. This is because among all the solutions x, namely all the real numbers, 
x=0 has the smallest magnitude. 

When MathLib has computed a solution x that minimizes R=B-A*X, how can 
you tell that is is unique? That depends on the shape of A. If A has more 
columns than rows, then X is never unique. If the number of A's rows is 
greater than or equal to the numbei" of A's columns., theri X will be unique if 
and only if A is of full rank. Fullness of rank is indicated by a condition 
number greater than zero. 

D.4.10.4 Ill-conditioned Problenns 

All the operations we have discussed are subject to roundoff errors during 
each floating-point operation. This has important implications because 
roundoff errors blur the distinction between matrices of full and deficient 
rank. A matrix may be of full rank, but if it is close enough to a 
rank-deficient matrix, the result X may not be satisfactory: it may be far 
from the correct solution X, and the residual R := B - A * X might not be 
minimal. The condition number COND supplies an estimate of the effect of 
roundoff: COND will be zero for singular and rank-deficient matrices A and 
gi-eater than zero for nonsingular and full rank A. The largest possible value 
of COND is 1, which is attained by the identity and rotation matrices, among 
others. Generally, you can not count on more than 18+LOG10(COND) 
significant digits being correct in the largest component of X, with fewer 
reliable digits in smaller components. But occasionally X will by chance be 
more accurate than COND suggests. 

COND is actually an estimate of the relative change in A to make A into 
the nearest rank-deficient matrix. Matrices with small COND often cause 
trouble because they are close to rank-deficient. The corresponding 
transformations map the unit circle into very skinny ellipses, which from a 
distance look much like the line segments generated by rank-deficient 
transformations. Two points on opposite sides of such a skinny ellipse may 
be very close together, perhaps within a rounding error, but the corresponding 
points on the unit circle that they were mapped from may be much further 
apart. So small errors like rounding errors can cause big errors when 
computing solutions X to linear equations or least squares problenns. 

D.4.10.5 Determinants 

MathLib provides routines to obtain the determinant of a square matrix. The 
determinant is not defined if the matrix is not square. 

The determinant of a square matrix has valid uses in statistical 
computations, but the determinant is most often used inappropriately as a x 
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criterion for singularity. The determinant of a singular square matrix is zero 
and the determinant of a nonsingular square matrix is not zero, but a 
nonzero determinant tells nothing about the condition of the problem. 
Consider a two-by-two matrix A with u and v on the diagonal, |u| < |v|, and 
zeros off the diagonal. The determinant is u*v, and the condition number is 
|u/v|. The distance to the nearest singular matrix is |u|; this distance 
relative to A is |u/v|, the condition number. Both the determinant and 
condition number are zero if A is singular, an infrequent occurrence; only the 
condition number is helpful in the far more common case when A may be 
nearly, but not quite, singular. Since the determinant can only be used to 
distinguish singular from nonsingular, and rounding errors blur this distinction, 
the use of the determinant is not recommended. Use COND instead. 

D.4.10.6 Iterative Improvement 

Iterative improvement is a technique for refining a first approximation to a 
solution of a linear equations or linear least squares problem. Given an 
approximate solution XO, iterative improvement computes a residual R := B - 
A * XO and then solves the equation R = A * DX using a factorization of A. 
Then the improved solution is XI .-= XO + DX. Usually one iteration 
improves the residual and moves XI closer to the conect answer- 
Subsequent iterations are sometimes helpful but they may worsen R, Xn, or 
both. 

The LinSys operators in LisaCalc and Lisa BASIC alwaj/s perform one 
iteration of iterative improvement. 

D.4.10.7 Statistical Computations with f^(\ 

Many important statistical problems of regression are formulated in terms of 
the matrix A'^^A, which is the matrix product of A^, the transpose of A, with 
A itself. For instance the solution of the linear least squares problem 
"choose X to minimize the length of B-A*X" is the same as the solution of 
the linear equation 

ATA * X = AT * B 

in exact arithmetic. But since the solution must be computed in the 
presence of rounding errors and A may be rank-deficient or nearly so, least 
squares problems are better solved without forming A^A. 

MathLib does provide two procedures for solving problems formulated in 
terms of A^A. Neither computes A^A or its factorization; instead the 
solutions are more accurately determined from the factorization of A itself. 
Standard errors can be determined from the diagonal elements of the inverse 
of AT A; these can be obtained by solving 

ATA * X = Identity 
Determinants of ATA are of interest when AT A is a correlation matrix. 
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D.4.10.8 Linear Algebra Procedures 
Procedure MatJIult ( 

n : integer ; 
overly : toolean ; 



var erroar : bcKilean 



{ Matrix mjltiplication B := ft * X. } 
{ Rows of A == TOWS of B. } 
{ ColuRms of A s rows of X. } 

{ ColUMlS of X = COlUHHIS of B. } 

{ True if B overlafus A or X; tenpcorary 

B is created on heap and copied at 

end. } 
{ True if failure due to lack of heap 

s|»ce. Not |M)ssible if overlap 

false. } 

var aij : 



procedure afetch ( i^j : integer 
{ User routine to prosd.de aij 
{ Afetch nsy assui^ 1 <= i <= n, 1 <= j 

procedure xfetch ( i, j : integer ; var xij 
{ User routine to provide xij 
I Xfetch nay assume 1 <= i <« 

procedure bstore ( i^ j : integer ; 

{ User routine to store B[i, j] : 
{ Bstore nay assme 1 <= i <= n. 



); 
Procedure OR_Factar ( 



:=X[i,j] 

P. 1 <= J 
bij : 

bij- } 
1 <= j <= n. 



Extended ) ; 
} 

<=P- } 
Extended ) ; 

) 

<= n. } 
Extended ) 



} 



p : integer ; 
pivot : boolean 



{ Coipute the OR factorization of 

natrix A.} 
{ Number of rows of A. } 
{ l^fcnber of colunms of A. } 
{ True if pivoting is to be perfomed, 
false if not. } 

var OR : P_ORJRecard ; { Pointer to factorization of A, which 

will te created in tte heap in an 
internal fomat. OR will be ard(NIL) 
if insufficient heap space is 
available. } 

: integer ; var aij : Extended ) ; 
{ User routine to provide aij := A[i, j]. } 
{ Afetch nay assume 1 <= i <= n, 1 <= j <= p. } 



prcM::edkjre afetch ( i, j 



Procedure OR.Condition ( 



OR : PjOR_Record ; 

var cond : Extended 

) 7 



{ Estinate condition nunber of 
natrix whose factorization is in 
OR*. } 

{ OR'^ is a deconposed natrix 
produced by OR_FsH;tor. } 

{ Estinate of comlition nunber. } 
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Procedure QR_Deteininant ( 



OR : PJJR.Recard ; 

vaor det : Extended 
); 

Procedure QR_Solve ( 



{ CoifNJte deteminvit of 
iiatrix whose factorization is in 
OR". } 

{ QR'^ is a decomposed matrix 

produced by OR_Facttxr. } 
{ Determinant. } 



m : integer ; 

OR : P_OR_Recard ; 

var error : boolean 



{ Con^MJte X = pseudo-inverse(QR'') * B 
to solve linear ecpjations or linear 
least squares problems. } 
{ NuBiber of coltiMis of X and B. } 
{ OR^ is a decomposed matrix 

produced by QR_Factor. } 
{ True if procedure failed 
{ftj» to lack of heap space. } 
pnrocedure bfetch ( i, j : inte^psar ; var bi j .- Extended ) 
{ User routine to provide bij := B[i, j]. } 
{ Bfetch may asstne 1 <= i <= n, 1 <= j <» m. } 
prm^edure xstore ( i, j : integer ; xi j : Extended ) ; 

{ User routine to store Xji, j] := xij. } 
I Xstore may assune 1 <= i <= p, 1 <= j <= m. } 



); 
Pr(M:edure QR_Resifftjal ( 



p : integer 
m : integer 
pnrocedure 



procedure 



procedure 



procedure 



); 



{ Compute residual R := B - AX for a 
linear eqpjations or linear 
least-squares problem } 

{ Nunriser of rows of A. } 

j hAirtier of colunns of A. } 

{ Number of columns of X arui B. } 
: integer ; var aij : Extended ) ; 

ft[i,j]- } 
n, 1 <= j <= p. } 



afetch ( i, J 
User routine to provide aij 
Afetch iMy assunMS 1 <= i <= 

bfetch ( i, j : integer ; var bij : Extentted ) 
User routine to provide bij := B[i, j]. } 
Bfetch may assume 1 <= i <= n, 1 <= j <= m. } 

xfetch ( i, j : integer ; var xij : Extended ) 
User routine to provide xij := X[i, j}. } 
Xfetch may assune 1 <= i <= p, 1 <= j <= m. } 

rstore ( i, j : integer ; rij : Extended ) 
User routine to store R[i, j] := rij. } 
Rstore may assune 1 <= i <= n, 1 <= j <= m. } 
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Rrocedkire QR.Inprove ( 



{ Perforn cme iteration to iaporove 
the solution X of a linear equations 
or liiwar least squares poroblei 
A ♦ X = B. ) 
n : integer ; { Number of colunms of X and B. } 

OR : P_QR_Record ; { W is a deco^M>sed matrix 

pro(ftjced by C)R_Factar. } 
{ True if OR_Inqnrove failed 
due to lack of heap sf^^e. } 
prcK^edure afetch ( i, j : integer ; var ai j : Extevided ) ; 



var error : bcralewt 



procedure 



procedkire 



procedure 



) 



} 
var bij : Extended ) 

:=B[i,j]. ) 



User rcHJtine to proviife aij := A[i^ j]. } 
ftfetch »ay assume 1 <= i <= n^ 1 <= j <= p. 

bfetch ( i, j : integer ; 
User rcMJtir^ to provide bij 
Bfetch iray assume 1 <= i <= n, 1 <= j <= m. } 

xfetch ( i, j : intecj^ ; var xi j : Extended ) 
User routine to provide xij := X[i, j]. } 
Xfetch may assume 1 <= i <= p, 1 <= j <= ra. } 

xstore ( i^ j : integer ; xij : Extended ) 
User routine to store X[i, j] := xij. } 
Xstore may assume 1 <= i <= p, 1 <= j <= ■>- } 



Procedure t)R_Tr(BunSolve ( 



m 
OR 



integer ; 
: PJ3R_Recard ; 



var error 



booleari 



{ Compute a solution for (ATA) X = B, 
ii#)ere T denotes transpose^ given 
factorization of A in QR^. } 
{ Number of columns of X and B. } 
{ OR"" is a decoiqrosed iraitrix 

produced by QR.Factor. } 
{ TriMS if priK^edure failed 
due to lack of Nsap space. } 
iaorocedure bfetch ( i, j : integer ; var bij : Extendhsd ) 
{ User routine to provide bij := B[i, j]. } 
{ Bfetch ma/ asstue 1 <= i <= p, 1 <= j <= »• } 
procedure xstore ( i, j : integer ; xij : Extended ) 

{ User routine to store X[i, j] := xij. } 
{ Xstore may assume 1 <= i <= p, 1 <= j <= m. } 



) 



Procedure QRJTranDeteininwit ( 
QR : PJ3R_Recard ; 



var det 
) ; 



Extended 



{ Compute determinant of ATA 
given factorizaticm of A in QR'". } 

{ QR^ is a deconfiosed matrix 
produced fay QR_Factor. } 

{ Deteimineffit . } 
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Mat_Mult performs matrix multiplication in order to determine the effect of 
a linear transformation upon one or more vectors or upon another linear 
transformation. The user specifies the dimensions of arrays A, X, and B, and 
defines procedures that provide access to the elements of these arrays. 
Mat_Mult is not concerned with the internal organization of the arrays, which 
may be more general or of a different structure than the array type defined 
in the Pascal language. N1at_Mult calls the user-defined -fetch and -store 
proceditres (afetch, xfetch, etc.) to fetch or store the (ij) element of the 
user's arrays. 

The result B may overlap the inputs A or X. If so, Mat_Mult must compute 
a temporary copy of B prior to storing any of it lest an input be overv-ritten 
prematurely. The boolean overlap is specified by the user accordingly. If 
the user has specified that the data overlap, then Mat_Mult creates its 
temporary copy of B on the Pascal heap. If the heap is nearly full then 
there may not be sufficient room to hold B. Then Mat_Mult will terminate 
and set the boolean error true prior to performing any computation. If the 
user sets overlap true prior to the call then he must check error after the 
call. Any heap space used by Mat_Mult is released prior to returning. 

The following example illustrates a typical use of Mat_Mult and 
demonstrates overlapping X and B as well as how to create and access a 
matrix A which is larger than 32768 bytes, the limit for a Pascal data 
structure. 

const n = 1000 ; 
p= 100; 
n = 2 ; 

var a : longint ; 

aifactcxr : longint ; { alfactor * 1 <= ^400000 requires 32 bit 

integers } 
ajfactcxr .- integer ; { ajfactor ♦ j <= 400 requires 16 

bit integers } 

b : array [ l..n, l.-ni ] of real ; 
errcnr .- booleen ; 

prcK:edure fetcha( i, j : integer ; var aij : Extended ) ; 
var pr : * real ; 
fc^pLn 

pr := pointer( a + aifsK^tor * i + ajfactar * j ) ; 

S2X( pr*, aij ) ; 
end ; 
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jirocedhire fetchx( i, j : integer ; var xij : Extended ) ; 
begin 

S2X( b[i,jL xij ) , 
end ; 

porocedure stareb( i, j : integer ; bij : Extended ) ; 

b^in 

X2S( bij, b[i, j] ) ; 
end ; 

{ Create space for a on heap. } 

a := FP_New( ard4( n ) ♦ ard4( p ) ♦ SizeOf( real ) ) ; 

if a = c]rd4(nil) then 

{ no room for a! } 
else begin 

ai factor := SizeOf(real) * ard4( p ) ; 

ajf actor := SizeOf(real) ; 

a := a - ai factor - ajf actor ; 

{ a will point to a[0,0] to improve the efficiency of afetch. } 

{ Now fill a with its elenents, and b with the elements of x. } 

ltetJ1ult( n, p, m, true, eorror, fetcha^, fetchx, storeb ) ; 

if error then { not enough roan on heap } else { OK } 
end ; 

D.4.10.9 QR Factorizafcion 

The MathLib routines to solve systems of linear equations A * X = B and 
linear least squares problems depend on first obtaining the QR factorization 
of the matrix A. Every n-by-p matrix A can be factored into a product of 
two matrices Q and R. 

The n-by-n orthogonal matrix Q represents an n-dimensional rotation of the 
coordinate axes and so preserves lengths of vectors. The inverse of Q is just 
its transpose Q""^. 

The n-b-y-p triangular matrix R hss zeros below the diagonal: if i > j then 
R[iJ = 0. This form makes R * X = Q^ * B easier to solve for X than 
A * X = B. In MathLib, QR_Factor performs the factorization A = Q * R, 
and QR_Solve computes X. 

It turns out that smaller residuals B-A*X can often be obtained if a process 
called column pivoting is performed during the QR factorization. This 
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amounts to performing the factorization first on the column of largest norm, 
then on the column of largest norm among those remaining, and so on. The 
effect is to produce three factors Q * R * P = A, where P is a p-by-p 
permutation matrix.- an identity matrix with some of the rows interchanged. 
Column pivoting is optional in QR_Factor since some matrices can be 
analyzed in advance to show that they do not require it. But if column 
pivoting has not been shown to be unnecessary then it should be performed. 
Pivoting usually improves accuracy but it may slow down the factorization by 
a factor of five to ten per cent for square matrices. LisaCalc and Lisa 
BASIC always perform column pivoting. 

QR_Factor stores the factorization QRP in a condensed internal form on the 
Pascal heap. QR_Factor returns a pointer to the factorization for use by the 
other QR routines. None of these other roLJtines releases the heap space 
allocated by QR_Factor, so it is up to the user to mark the heap before 
calling QR_Factor and to release the heap to the same mark when that 
factorization is no longer required. The other QR routines that allocate 
space on the Pascal heap release that space before returning. All the QR 
routines that require heap space contain an error flag in their calling 
sequences and terminate without storing any result if sufficient heap space is 
not available. 

D.4.10.10 MathLib QR Procedures 

QR_Factor is the factorization routine. Its inputs describe A; its output is a 
pointer to the factorization QRP. That pointer and factorization are only 
useful to the other QR routines in MathLib. About 18 + lOnp bytes are 
allocated on the heap if pivoting is not requested; pivoting requires an 
additional 20p bytes. Execution time is proportional to n' for an n-by-n 
matrix. 

QR_Determinant computes the determinant of A very quickly given A's QR 
factorization. A NaN is returned if the matrix A is not squaie. 

QR_Condition provides an estimate of the condition number of A with 
respect to solving linear equations or least squares problems. Conventionally 
this condition number is defined to be the ratio of the largest singular value 
of A to the smallest, and thus ranges from 1 upward to infinity. 
QR_Condition inverts this ratio and so returns a number ranging from 1 down 
to 0. Furthermore, since computation of singular values is fairly time 
consuming, QR_Condition only makes an estimate of the largest and smallest 
singular values, which sometimes may vary substantially from the correct 
values. Execution time is about twenty percent of the time required for the 
factorization. QR_Condition requires lOp bytes of heap space. 

QR_Solve finds the X in A * X = B given A's factorization. It requires 

10 * max(n,p) bytes of heap space. The j'th column of X may overwrite the 

j'th column of B. 
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QR_Resicluatl provides a convenient computation of the residual 

R := B - A * X, not to be confused with the R in the QR factorization! 

QRJmprove uses QR_Residual and QR_Solve to perform one iteration of 
improvement of the solution X. 

QR_TranSolve computes a solution X of A^A * X = B from the QR 
factorization of A. 

QR_TranDeterminant computes the determinant of A'^A from the QR 
factorization of A; even if A has no determinant, A^A is always square and 
always has a determinant. 

D.4.10.11 QR Example 

The following example codes a procedure LinSys that works somewhat like 
the LinSys in LisaCalc and Lisa BASIC, but its arguments are limited to 
Pascal real arrays. 

LinSys solves m linear least squares problems: 

"For k=l to m, find xi^k to minimize the length of 

ri,k = (ai,iXi,k + ai.2X2,k + ... + ai,pXp,k) - bi,i< 

3^n,k = (8n.iXi,k + ah,2X2,k + ... + an,pXp,k) - bn,k "• 
If rj,K =0 then Xi^k also solves the m systems of linear equations 
»L,iXi,k + ai,2X2,k + . - - + ai,pXp,k = ^.v. 

8n.iXi,k + Sn,2X2,k + . - - + 8n,pXp,K = bn,k 



type atype = array 
btype = array 
xtype = array 



l..n,l..ii 



of real ; 
of real : 



l..p, l-.ipi] of real ; 



var aiaatrix : atype ; 
bnatrix : tity^ ; 
xmatrix : xtype ; 

ctet, cond : real ; 

{ Last determinant and condition nu^er coi^nited by linsys. } 

function linsys ( a: atype; b: btype; var x.- xtype ) : boolean ; 

{ Linsys will find x to minimize b-a*x, if possible; will return a 
function value of FftLSE if successful, TRUE otherwise; will 
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update ttet and cond with the deteominant and condition estiimte 
for a. } 

var marker : *" integer ; 
qr : PJ3R_Recard ; 
errcnr : kKM>lean ; 



procedure fetcha( i, j : 
fc^in 

S2X( a[i,jL aij ) ; 
end ; 

procedure fetchb( i, j 
begin 

S2X( b[i,jL bij ) 
eraJ ; 



integer ; var aij : extended ) ; 



integer ; var bij : extemled ) ; 



procedure storexC i, j : integer ; 
begin 

X2S( xij, b[i, j] ) ; 
end ; 



xij : extoMted ) ; 



procedure retchx( i, j : int^ier ; var xij 
begin 
S2X( b[i, JL xij ) ; 



extend«l ) ; 



tegin { linsys } 
nark(iBarker) ; | Hark te^ storage for subsequent release. } 

QR_Factar( n, p, {pivot} true, qr, fetcha ) ; 
if qr = ord4(nil) then error := true 
else begin { factorizaticm OK } 
CIRJ>eteiiiinwit ( qr, det ) ; 

ORjCondition ( qr, corui ) ; { Cond exxor represents by HeU.) 
QR_Solve( a, qr, erxoor, fetchb, storex ) ; 
if not error then begin { solve GK } 
QR.Inprove ( m, qr, error, fetcha, fetcM), fetchx, storex); 
{ Only one improvenent iteration. } 
ervA { solve OK } ; 

end { factorizatitm OK } ; 

linsys .-= error ; 

Telease(narker) ; { Release heap storage. } 
«id { linsys } ; 
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D.4.11 MflfchLib l^aNs 

Besides the NaNs that can be generated by the procedures in FPLib^ there 
sre some NaN codes that are used by the procedures in MathLib to signify 
unusual results: 

Name Dec Hex Meaning 

NaNIRR 39 $27 Internal rate of return is not real, does 

not exist, or was not found. 

NaNDet 49 $31 nonsquare matrix has no determinant. 

NaNCond 50 $32 Condition estimate could not be canputed 

because of inadequate heap space. 
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D.4.12 MathUb Interface 

UNIT MathLib ; INTRINSIC ; 

INTERFACE 

{ Lisa Math Library. } 

{$C Copyright 1983, 1984, Apple Computer Inc. } 

USES FPLib ; 

CONST 

{ Lisa liath Library constants. } 

RandModulus = 2147483647 ; 

{ Prime modulus for random nutiber generation = 2'^31-1. } 

LSigDigLen = 30 ; { Length of significand string. } 

TYPE 

{ Lisa Math Library types. } 

RoundPrecision = ( ExtPrecision, DblPrecision, RealPrecision) ; 

Type FP Type = ( TFP byte, TFP integer, TFP_longint, TFP_Comp, TFP_real, 
TFP_Double, TFP_Ex tended ) ; 
{ Number type nannes for FP_size.} 

Free_Format = record { Specifications for free-form output. } 

MaxSig : integer ; { Maximum number of significant digits. } 

Sig_FForm, { True if "fixed" style applies MaxSig to 

significant digits; false if to digits after 

the point. } 
Trail_Point^ { True if trailing point should be printed for 

inexact values in "integral" style. } 
Int_EForm, { True if "exponential" style acceptable for 

integral values. } 
Plus_EForm : boolean ; { True if "exponential" style should exhibit 

+ sign for positive exponents. } 
end ; 

P_OR_Record = longint ; { Pointer to matrix factored as C^. } 
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LongSigDig = string [LSigDigLen] ; 

LongDecimal = record 

sgn : . . 1 ; 
exp : integer ; 
sig : LongSi^ig ; 
end ; 



{- 



{ Elementary functions to support BASIC and Fortran. } 



procedure ftSinX ( var x .- Extended ) ; { x := asin(x) } 
procedure ACosX ( var x : Extended ) ; { x := acos(x) ) 



procedure SinhX ( var x : Extended ) ; { x 
procedure CoshX ( var x : Extended ) ; { x 
procedure TanhX ( var x : Extended ) ; { x 



= sinh(x) } 
= cosh(x) } 
= tanh(x) } 



{- 



{ Procedures to support polar coordinates. } 



procedure ftbs2X ( x, y : Extended 
procedure ftTan2X( x, y : Extended 



var z : Extended ) ; { z 
var z : Extended ) ; { z 



:= abs(y+ix) } 
:= 8rg(y+ix) } 



{- 



{ Random number procedure. } 

function NextRandom ( lastrandom : longint ) .- longint ; 

{ Returns next "randwn" longint with 1 <= nextrandom <= Rancfiiodulus-1.) 



{- 



•} 



{ Floating point status and mode procedures. } 

procedure ClearXcps ; { Turns off all exception flags. } 

procedure ClearHlts ; { Turns off all halt flags. } 
procedure SetPrecision ( p .- RouncPrecision ) ; 

{ Set extended rounding precision. } 
function GetPrecision : RouncPrecision ; 

{ Get extended rounding precision. } 

{ 
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{ Sort procedure. } 

procedure liath_Sort ( { General procedure to stably sort an arbitrary list.} 
firsts last : integer ; { Records first.. last will be sorted. } 

function Sorted ( i, j : integer ) : boolean ; 

{ User-supplied procedure called by Math_Sort to compare order of 
records i and j. Math_sort guarantees first <= i < j <= last. 
Sorted returns true if records i and j are already correctly 
sorted with respect to each other. } 
procedure Swap ( i, j : integer ) ; 

{ User-supplied procedure called by Math_Sort to swap records i 
and j. Math_sort guarantees first <= i < j <= last. } 
var error : boolean ) ; { True if sort routine failed due to 

insufficient heap space available. } 

I 



{ Miscellaneous utility procedures. } 
function SigrOfX ( x : Extended ) : boolean ; 



{ True if X has neg sign. } 



function FP_New ( n .- longint ) : longint ; 

{ Attempts to allocate n bytes on heap, returning address. 
Returns ord4(nil) if space not available. } 

procedure FP_Size ( x: Extended ; var sgn: integer ; var class: NumClass ; var 
size: FPJType ) ; 
{ Returns sign bit, class, and size of smallest type that 
would hold X exactly. } 



procedure FP_Free_fta::^II ( 
X : Extended ; 
width : integer ; 
form : Free_Format; 
var s : Decstr ) ; 



Procedure to provide free-form ASCII output . } 
Nimber to be converted fran binary to f^CII. } 
Maximum number of characters in output string. } 
Detailed format specifications. } 
Output destination string. If, after call, 
length(s) > width, then x was inconsistent with 
the constraints Width or MaxSig. } 



•} 



{ Financial analysis procedures. } 



procedure Fin_Npv 
first, 
last, 
net : integer • 



( { Cwnpute net value of series of payments. } 
{ First payment period. } 
{ Last payment period. } 

{ Period at which net value is to be ccmputed; 
need not be between first and last. } 
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rate : Extended ; { Periodic interest rate. } 
var Npv : Extended ; { Net payment value. } 
Procedure payment ( i -. integer ; var pmt -. Extended ) 

{ User-supplied procedure to provide pmt, the payment at 
period i. } 

{ Fin Npv guarantees first <= i <= last. } 
); 

procedure Fin_Return ( { Analyze series of payments for external or internal 

rate of return. Discounting fay external rates may be 
specified for positive or negative payments or both or 
neither. Standard internal rate of return is obtained 
by specifying, for example, negperiod, posperiod .-= 
first-1. A conservative external rate of return is 
obtained by considering negative payments as out from 
the investor, positive payments as in to the investor, 
and specifying: 

negperiod := first ; 

posperiod := last ; 

negrate := guaranteed safe rate of return ; 

posrate := expected average portfolio reinvestment 
rate of return. } 

first, { Initial payment period. } 

last : integer ; {Final payment period. } 

negperiod, posperiod : integer ,- 

{ Periods to which negative or positive payments 
are to be discounted; if < first or > last then 
corresponding payments are not discounted. } 
negrate, posrate : Extended ; 

{ Discount rates for negative and positive payments 
respectively; ignored if corresponding period 
does not satisfy first <= ...period <= last. } 
var ncs : integer ; { Error code = number of changes of sign among 

adjusted payments; on normal return ncs = 
l.ncs = -2 if an inf or NaN payment was 
supplied. } 
var ret : Extended ; { Rate of return: if ncs = 1 then ret will 

contain the single real root > -1; if ncs > 
1 then ret will contain some real root > -1 if 
ncs is odd; if ncs > 1 is even ret may contain 
a real root > -1; otherwise ret will contain 
NaN. } 
Procedure payment ( i : integer ; var pmt : Extended ) 
{ User-supplied procedure to provide prat, 
the payment at period i. } 
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) ; 



{ Fin_Npv guarantees first <= i <= last. } 



{ 



{ Numerical algebra. } 
procedure Mat_Mult ( 

P, 

rn : integer ; 

overlap : boolean ; 

ver error : boolean ; 

procedure afetch ( i, j 

procedure xfetch ( i, j 

procedure bstore ( i^ j 

) ; 
procedure (:y?_Factor ( 

p : integer ; 
pivot : boolean ; 

var OR : P_OR_Record ; 



procedure afetch ( i., j 

) ; 

procedure CRjCondition ( 

OR : P_OR_Record ; 

var cond : Extended 
) ; 






{ Matrix multiplication B := ft * X. } 

{ Rows of A = rows of B. } 

{ Columns of ft = rows of X. } 

{ Columns of X = columns of B. } 

{ True if B overlaps ft or X; temporary B is 

created on heap and copied at end. } 
{ True if failure due to lack of heap space. 

Not possible if overlap false. } 
integer ; var aij : Extended ) ; 
{ User routine to provide aij := A[i/ j]. 
{ Afetch may assime 1 <= i <= n, 1 <= j <= p. 
: integer ; var xij : Extended ) 
{ User routine to provide xij 
{ Xfetch may asstffne 1 <= i <= 
: integer ; bij : Extended ) 

{ User routine to store B[i, j] := bij. 
{ Bstore may assume 1 <= i <= n^ 1 <= j <= m. 



;= X[i,j]. 

p, 1 <= j <= m. 



{ Compute the OR factorization of matrix ft. } 

{ Number of rows of ft. } 

{ NLBnber of colimns of ft. } 

{ True if pivoting is to be performed^ false if 

not. } 
{ Pointer to factorization of A, which will be 

created in the heap in an internal format. 

OR will be ord(NIL) if insufficient heap 

space is available. } 
integer ; var aij : Extended ) ; 
{ User routine to provide aij := A[i, j3- } 
{ Afetch may assume 1 <= i <= n, 1 <= j <= p. } 



{ Estimate condition number of 

matrix whose factorization is in C^". } 
{ t^" is a decomposed matrix produced by 

(^_Factor. } 
{ Estimate of condition nieber. } 
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procedure (^.Determinant ( 

OR : P_OR_Recorcl ; 

vacr det : Extended 
) ; 

procedure OR_Solve ( 



{ Compute determinajit of matrix whose 

factorization is in QR*^. } 
{ OR'' is a decomposed matrix produced by 

OR_Factor. } 
{ Determinant. } 



OR 



integer ; 
; P_OR_Record ; 



var error 



{ Compute X = pseudo-inverse(W) * B to Solve 

linear equations or linear least squares 

problems. 
{ Number of columns of X and B. 
{ W'^ is a decomposed matrix produced by 

OR_Factor. 
{ True if procedure failed due to lack of heap 

space . 
: integer ; var bij : Extended ) 
{ User routine to provide bij := B[i, j]. 
{ Bfetch may assime 1 <= i <= n, 1 <= j <= m. 
procedure xstore ( i, j : integer ; xi j : Extended ) ; 

{ User routine to store Xji, j] .-= xij. 

{ Xstore may assume 1 <= i <= p, 1 <= j <= m. 



boolean ; 
procedure bfetch ( i, j 



J 



procedure W_Residual ( 



p : integer ; 
m : integer ; 
procedure afetch ( 



i, j 



procedure bfetch ( i, j 



procedure xf etch ( i^ j 



procedure rstore ( i, j 



procedure OR_Improve ( 



m : integer ; 



{ Compute residual R := B - ftX for a linear 

equations or linear least squares problem. 

NuTfiber of rcws of A. 

Number of coltBuns of ft. 

Number of columns of X and B. 
integer ; var aij : Extended ) ; 

User routine to provide aij := A[i, j]. 

Afetch may assLBtie 1 <= i <= n, 1 <= j <= p. 
integer ; var bij : Extended ) 

User routine to provide bij := B[i, j]. 

Bfetch may assume 1 <= i <= n, 1 <= j <= m. 
integer ; var xij : Extended ) ; 

User routine to provide xij := X[i, j]. 

Xfetch may assume 1 <= i <= p^ 1 <= j <= m. 
integer ; rij .- Extended ) 

User routine to store R[i, j] := rij. 

Rstore may assiroe 1 <= i <= n, 1 <= j <= m. 



Perform one iteration to improve the 
solution X of a linear equations or linear 
least squares problem A * X = B. } 

NLffnber of columns of X and B. ) 
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OR : P_OR_Recorcl ; 
var error : boolean ; 
procedure afetch ( i, j 

procedure bf etch ( i^ j 

procedure xf etch ( i, j 

procedure xstore ( i, j 

) ; 
procedure OR_TranSolve ( 

ro : integer ; 

OR : P_OR_Record ; 

var error : boolean ; 

procedure bf etch ( i, j 

procedure xstore ( i^ j 

3 ; 

procedure OR_TranDeterminant 

OR : P_OR_Record ; 

var det : Extended 
) ; 



{$t is a decomposed matrix produced by 

OR_Factor. } 
True if procedure failed due to lack of heap 

space . } 

integer ; var aij : Extended ) ; 

User routine to provide aij := A[i/ j]. } 

ftfetch may assume 1 <= i <= n^ 1 <= j <= p. } 

integer ; var bij : Extended ) 

User routine to provide bij := B[i, j]. } 

Bfetch may assume i <= i <= n, 1 <= j <= m. } 

integer ; var xij -. Extended ) ; 

User routine to provide xij .-= X[i^ j]. } 

Xfetch may assume 1 <= i <= p, 1 <= j <= m. } 

integer ; xij : Extended ) 

User routine to store X[i, j] := xij. } 

Xstore may assume 1 <= i <= p., 1 <= j <= m. } 



Compute a solution for (ATA) X = B^ where T 
denotes transpose, qiven factorization of ft 
in OR". } 

NtHttber of col tons of X and B. } 

{^'^ is a decomposed matrix produced by 
OR_Factor. } 

True if procedure failed due to lack of heap 



space . 
integer ; var bij : Extended ) 

User routine to provide bij .-= B[i^ j]. 

Bfetch may assyme 1 <= i <= p^ 1 <= j <= m. 
integer ; xij : Extended ) 

User routine to store X[i, j] := xij. 

Xstore may assime 1 <= i <= p, 1 <= j <= m. 



{ CcMTftpute determinant of ATA given 

factorization of A in ^^ . } 
{ CR" is a decomposed matrix produced b*</ 

(^_Factor. } 
{ Determinant. } 



} 



{ Procedures for correctly rounded conversion between binary and 
decimal . } 



D-77 



Pascal Reference Manual 



Floating-Point f^ithmetic 



procedure X2LDec ( f : DecForm ; x : Extended ; var y : LongDecimal ) ; 
{ Converts x to y^ correctly rounded according to f . } 

procedure LDec2X ( prec: RouncPrecision; x: Lon^ecimal; var y.- Extended ) 
{ Converts x to y^ correctly rounded according to prec. } 



{■ 



{ hJuraerical analysis. } 



procedure Math_Solve ( 

estl, est2 : Extended 
var res 



Extended 



{ Computes zero of function. } 
{ A priori estimates of zero. } 
{ f(res) may = or NaN or its sign may differ 
from one of its neighbors or it may merely 
be the x with minimal abs(f(x)) among those x 
sampled by Math_Solve. The user must decide 
the significance of the result res. } 
procedure f ( x : Extended ; var fx .- Extended ) 

{ User-supplied procedure to evaluate fx = f(x). } 
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D.5 Macintosh Roaling-Point ProgFanvning 

Sections D.2, D.Z, and D.4 describe floating-point programming for the Lisa. 
Floating-point programming for the Macintosh is similar; the changes are 
described below. 

Assembly-language programs that use FP68K may be assembled on the Lisa 
and run on the Macintosh or on MacWorks. Pascal programs that use real 
ai-ithmetic or the intrinsic units FPLib or MathLib mey be compiled with the 
Lisa Pascal Compiler and run on Macintosh or Macworks. 

WARNING 

Early Macintosh developers received the files: 

INTRFC/SANE.TEXT OBJ/SANE.OBJ OBJ/SANEAsm.OBJ 
INTRFC/Elems.TEXT OBJ/Elems.OBJ OBJ/El eimsAsm.OB J 

which are no longer recommended, and older versions of the files: 

OBJ/MacPasLib.OBJ TLASM/ToolMacs.TEXT TLASM/SANEMacs.TEXT 

which have been replaced by newer versions distributed with the 
Macintosh software supplement. Do not mix any of these older files 
with the newer ones described below. 

D3.1 Assembly Laviguage 

Include the files TLASM/SANEMacs, TLASM/ToolEqu, and TLASM/ToolMacs 
with your assembly-language source files. It is not necessary to link with 
any other Lisa files to get assembly-language floating-point arithmetic. In 
the file TLASM/SANEMacs, the first equate, FPByTrap, must be 1 to run on 
Macintosh or MacWorks, or to run on the Lisa Operating System. 

D.5.2 Pascal Real Arithmetic 

It is not necessary to USE any Pascal files to compile Pascal real arithmetic. 
Link with the files: 

OBJ/RealPasUnit OBJ/FPUnit OBJ/FPSub OBJ/MacPasLib 

D^.3 FPLib tfid McdihLib 

Regular versions of the units FPLib and MathLib, called FPUnit and 
MathUnit, are available in the files OBJ/FPUnit and OBJ/MathUnit. Change 
your USES statement accordingly: 

USES {$U OBJ/FPUnit} FPUnit, 
{$U CBJ/HathUnit} HatNJnit ; 

Do not include {$U INTRFC/SANE} SANE or {$U INTRFC/Elems} Elems in 
your USES statement. 
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Link with the files: 

OBJ/MathUnit OBJ/FPUnit OBJ/Real PasUnit 
OBJ/FPSub OBJ/MacPasLib 

Only the procediffes you actually need will be linked into your object file. 
Do not link with: 

OBJ/SANE OBJ/SANE Asm OBJ/Elenns OBJ/ElemsAsm 

D3.A Restrictions 

Assembly-language programmers should clear the floating-point environment 
with FSetEnv prior to any floating-point operations. Pascal programmers 
should call 

Proceduore InitFPLib ; 

which is declared in the FPUnit interface, prior to any floating-point 
operations. 

MathLib depends on certain lOSPasLib procedures that are not implemented 
in OBJ/MacPseLib. Consequently, certain MathUnit procedures do not work 
reliably. Affected procedures include financial rate of return, matrix, and 
sorting. 
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E.1 Atxxjt This Appendix 

This appendix descrldes QuickDraw, a set of graphics procedures, functions, 
and data types that allows a Pascal or assembly-language programmer of Lisa 
to perform highly complex graphic operations very easily and very quickly. It 
covers the graphic concepts behind QuickDraw, as well as the technical 
details of the data types, procedures, and functions you will use In your 
programs. 

We assume that you are familiar with the Lisa Workshop Manager, Lisa Pascal, 
and the Lisa Operating System's memory management This graphics package 
Is for programmers, not end users. Although QuickDraw may be used from 
either Pascal or assembly language, all examples are given In their Pascal 
form, to be clear, concise, and more intuitive; Section E.ll describes the 
details of the assembly-language Interface to QuickDraw. 

The appendix begins with an Introduction to QuickDraw and what you can do 
with It (Section E.2). It then steps back a little and looks at the mathemat- 
ical concepts that form the foundation for QuickDraw: coordinate planes, 
points, and rectangles (Section E.3). once you understand these concepts, read 
on to Section E.4, which describes the graphic entitles based on them— how 
the mathematical world of plaies and rectangles Is trsnslated Into the 
physical phenomena of light and shadow. 

Then comes some discussion of how to use several graphics ports (Section E.6), 
a summary of the basic drawing process (Section E.7), and a discussion of two 
more parts of QuickDraw, pictures and polygons (Section E.8). 

Next, in Section E.9, there's a detailed description of all QuickDraw proce- 
dures and functions, their parstfneters, calling protocol, effects, side effects, 
cBid so on—all the technical Information you'll need each time you write a 
program for the Lisa 

Following these descriptions are sections that will not be of Interest to all 
readers. Special Information is given In Section E.IO for programmers who 
want to customize QuickDraw operations by overriding the standard drawing 
procedures. In Section E.ll for those who will be using QuickDraw from 
assembly language, and In Section E.12 for those Interested In creating 
three-dimensional graphics using the Graf3D unit 

Finally, there are listings of the QuickDraw Interface (Section E.13), two 
sample programs (Section E.14), and the QDSupport unit (E.15); and a glossary 
that explains terms that may be unfamiliar to you (Section E.16). 
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E2 /Ntxxjt QuickDraw 

QuickDraw allows you to organize the Lisa screen into a number of individual 
areas, within each area you can draw many things^ as illustrated in Figure 
E-1. 
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Figure E-1 
Samples of QirtckDraw's Abilities 



You can draw: 



• Text characters in a number of proportionally-spaced fonts^ with variations 
that include boldfacing^ italicizing^ underlining, and outlining. 

• Straight lines of any length and width. 

• A variety of shapes, either solid or hollow. Including: rectangles, with or 
without rounded corners; full circles and ovals or wedge-shaped sections; 
and polygons. 

• Any other arbitrary shape or collection of shapes, again either solid or 
hollow. 

• A picture consisting of any combination of the above items, with just a 
single procedure call. 

In addition, QuickDraw has some other abilities that you won't find in many 
other graphics packages. These abilities take care of most of the "house- 
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keeplng"~the trivial but time-consuming and bothersome ovemead that's 
necessary to keep things in order. 

• The ability to define many distinct ports on the screen^ each with Its own 
complete drawing environment—its own coordinate system^ drawing 
location character set, location on the screen, and so on. You can easily 
switch from one such port to another. 

• Full and complete clipping to arbitrary areas, so that drawing will occur 
only where you want It's like a super-duper coloring book that won't let 
you color outside the lines. You don't have to worry about accidentally 
drawing over something else on the screen, or drawing off the screen and 
destroying memory. 

• Off-screen drawing. Anything you cai draw on the screen, you cai draw 
into an off-screen buffer, so you can prepare an image for an output 
device without disturbing the screen, or you can prepare a picture and 
move it onto the screen very quickly. 

And QuickDraw lives up to its name! It's very fast. The speed and 
responsiveness of the Lisa user Interface are due primarily to the speed of the 
QuickDraw package. You can do good-quality animation, fast interactive 
graphics, and complex yet speedy text displays using the full features of 
QuickDraw. This means you don't have to bypass the general-purpose 
QuickDraw routines by writing a lot of special routines to improve speed. 

E.2.1 How To Use QuickDraw 

QuickDraw can be used from either Pascal or MC68000 machine language. It 
has no user interface of its own. 

If you're using Pascal, you must write a Pascal program that includes the 
proper QuickDraw calls, compile It against the files QD/QuIckDraw.CBJ and 
QD/QDSupportCBJ, link It with the files listed in QD/QDStuff.TEXT, and 
execute the linked object file. 

If you're using machine language, your program should Include the proper 
QuickDraw calls, and .INCLUDE the file QD/GRAFTYPES.TEXT. Assemble the 
program, link It with the files listed in QD/QDStuff.TEXT, and execute the 
linked object file. 

A programming model, QOSample, is included with the workshop software In 
the file QD/QOSample.TEXT (listed in section E.14.1); It shows the structure of 
a properly organized QuickDraw program. What's best for beginners Is to read 
through the text, »id, using the superstructure of the program as a "shell", 
modify It to suit your own purposes. Once you get the hang of writing 
programs inside the presupplied shell, you can work on changing the shell 
itself. 

Note that all files related to QuickDraw are prefixed by "QD/". 

QuickDraw Includes only the graphics and utility procedures and functions 
you'll need to create graphics on the screen. Procedures for dealing with the 
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mouse, curson, keytxDard, and screen settings, as well as those allowing you to 
generate sounds and read and set clocks and dates^ are described in ^^^pendix 
F, Hardware interface. 

E22 QuickDraw Data Types 

QuickDraw defines three general data types, QDByte, QDPtr, and QDHandle: 

type QOByte = -128.. 127 
QOPtr = *QOByte 
QOHandle = '^QOPtr 

other data types are described throughout this appendix in the sections in 
which they're relevant For a summary of all QuickDraw data types, see 
Section E.13.2. 

E.3 The Mathematical Foundation of QuickDraw 

To create graphics that are both precise and pretty requires not super-charged 
features but a firm mathematical foundation for the features you have. If the 
mathematics that underlie a graphics package are Imprecise or fuzzy, the 
graphics will be, too. QuickDraw defines some clear mathematical constructs 
that are widely used In Its procedures, functions, and data types: the coordi- 
nate plane, the point, the rectangle, and the region 

E3.1 The Coordinate Plane 

All information about location, placement, or movement that you give to 
QuickDraw is In terms of coordinates on a plane. The coordinate plane Is a 
two-dimensional grid, as Illustrated In Figure E-2. 
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Figure E-2 
The Coordinate Plane 
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There are two distinctive features of the QuickDraw coordinate plane: 

• All grid coordinates are Integen. 

• All grid lines are Infinitely thin. 

These concepts are Important! First, they mean that the QuickDraw plane Is 
finite, not Infinite (although It's very large). Horizontal coordinates range 
from -32768 to +32767, and vertical coordinates have the same range. 

Second, they mean that all elements represented on the coordinate plane are 
mathematically pure. Mathematical calculations using Integer arithmetic will 
produce intuitively correct results. If you keep in mind that grid lines are 
Infinitely thin, you'll never have "endpoint paranoia"~the confusion that 
results from not knowing s^'hether that last dot is included In the line. 

E.3^ Points 

On the coordinate plane are 4,294,967,296 unique points. Each point is at the 
intersection of a horizontal grid line and a vertical grid line. As the grid lines 
are infinitely thin, a point is infinitely small. Of course there are more points 
on this grid than there are dots on the Lisa screen: when using QuickDraw you 
associate small parts of the grid with areas on the screen, so that you aren't 
bound into an arbitrary, limited coordinate system. 

The coordinate origin (0,0) is in the middle of the grid. Horizontal coordinates 
Increase as you move from left to right, and vertical coordinates Increase as 
you move from top to bottom. This Is the way both a TV screen and a page 
of English text are scanned: from the top left to the bottom right 

You can store the coordinates of a point in a Pascal variable whose type is 
defined by QuickDraw. The type Point is a record of two integers, and has 
the following structure: 

type VHSelect = (V,H); 

Point = record case Integer of 

0: (v: Integer; 
h: integer); 

1: (vh: array [VHSelect] of integer) 

end; 

The variant part allows you to access the vertical and horizontal components 
of a point either indlvlcfcjally or as an array. For example, if the variable 
goodPt were declared to be of type Pdm, the following would all refer to the 
coordinate parts of the point: 

goodPt.v goodPt.h 

goodPt.vh[V] goodPt.vh[H] 



E-5 



Pascal Reference Manual 



QuickDraw 



E.5.3 Rectangles 

Any two points can define the top left and bottom right corners of a 
rectangle. As these points are Infinitely small the borders of the rectangle 
are infinitely thin (see Figure E-3). 
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Figure E-3 
A Rectangle 



Rectangles are used to define active areas on the screen, to assign coordinate 
systems to graphic entities, and to specify the locations and sizes for various 
drawing commands. (QuickDraw also allows you to perform many 
mathematical calculations on rectangles—changing tHeir sizes, shifting them 
around, and so on. 

NOTE 

Remember that rectangles, like points, are mathematical concepts that 
have no direct representation on the screen. The association between 
these conceptual elements and their physical representations is made Xy'^ 
a bitmap, described below. 
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me data type for rectangles is Rect, and consists of four integers or two 
points: 

type Rect = record case Integer of 

0: (top: Integers- 
left : integer; 
bottom: Integer; 
rl^t: integer); 

1: (topLeft: Point; 
botRlght: Point) 

end; 

Again, the record variant allows you to access a variable of type Rect either 
as four boundary coordinates or as two diagonally opposing comer points. 
Combined with the record variant for points, all of the following references to 
the rectangle named dRect are legal: 

dRect {type Rect} 

DRect.topLeft bRect.botRight {type Point} 

tjRect.top bRect.left {type integer} 
bRect.t(Y)Left.v bRect.topLeft.h {type integer} 
dRect. topLeft.vh[V] dRect. topLeft.vh[H] {type integer} 

dRect. dottom dRect. right {type integer} 
dRect. dotRic^t.v dRect .dotRight.h {type integer} 
dRect. dotRight.vh[V] dRect. dotRlgnt.vn[H] {type integer} 

WARNING 

If the bottom coordinate of a rectangle is equal to or less than the top, 
or the right coordinate is equal to or less than the left, the rectangle 
is an empty rectangle (i.e., one that contains no bits> 

E3.4 Regions 

Unlike most graphics packages that can manipulate only simple geometric 
structures (usually rectilinear, at Uiat), QuickDraw can gather an arbitrary set 
of spatially coherent points into a structure called a region, and perform 
complex yet rapid manipulations and calculations on such structures. This 
remarkable feature not only will make your standard programs simpler and 
faster, but will let you perform operations that would otherwise be nearly 
impossible; It Is fundamental to the Lisa user interface. 
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You define a region by drawing lines, shapes such as rectangles and ovals, or 
even other regions. The outline of a region should be one or more closed 
loops. A region can be concave or convex, can consist of one area or many 
disjoint areas, and can even have "holes" in the middle. In Figure E-4, the 
region on the left has a hole in the middle, and the region on the right 
consists of two disjoint areas. 
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Figure E-4 
Regions 

Because a region can be any arbitrary area or set of areas on the coordinate 
plane, it takes a variable amount of information to store the outline of a 
region. The data structure for a region, therefore, is a variable-length entity 
with two fixed fields at the beginning, followed by a variable-length data 
field: 

type Region = record 

rgnSlze: Integer; 
rgnBBox: Rect; 

{optional region definition data} 
end; 

The rgnSlze field contains the size, in bytes, of the region variable. The 
ignBBox field is a rectangle which completely encloses the region. 

The simplest region is a rectangle. In this case, the rgnBBox field defines the 
entire region,, and there is no optional region data For rectangular regions (or 
empty regions), the rgnSlze field contains 10 (two bytes for rgnSize, plus 
eight for ignBBox). 

The region definition data for nonrectangular regions is stored in a compact 
way which allows for highly efficient access by QuickDraw procedures. 
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As regions are of variable size, they are stored dynamically on tne neap, and 
the Operating System's memory management moves them around as their sizes 
change. Being dynamic, a region can oe accessed only through a pointer; but 
when a region is moved, all pointers referring to it must be updated. For this 
reason, all regions are accessed through nancaes, which point to one master 
pointer which in turn points to the region. 

type RgnPtr = ^Region; 
RgnHandle = "RgnPtr; 

When the memory management relocates a region's data in memory, it updates 
only the RgnPtr master pointer to that region. The references through the 
master pointer can find the region's new home, but any references pointing 
directly to the region's previous position in memory would now point at dead 
bits. To access individual fields of a region, use the region handle and double 
Indirection: 

inyRgn^^.rgnslze (size of region whose handle is myRgn} 

RiyR^^^.rgpiBBox {rectangle enclosing the same regior| 

RQrt^^^.rgnBBox.top {minimum vertical coordinate of ail points 

in the region} 
RtyRgn^.rgnBBox {semantically Incorrect; will not compile if 

myRgn is a rgnHandle} 

Regions are created by a QuickDraw function which allocates space for the 
region, creates a master pointer, and returns a region handle. When you're 
done with a region, you dispose of it with another QuickDraw routine which 
frees up the space used by the region, only these calls allocate or deallocate 
regions; do not use the Pascal procedure new to create a new region! 

You specify the outline of a region with procedures that draw lines and 
shapes, as described in Section E.9, QuickDraw Routines. An example Is given 
In the discussion of CloseRgn In section E.9.11, calculations with Regions. 

Many calculations can be performed on regions. A region can be "expanded" 
or "shrunk" and, given any two regions, QuickDraw can find their union, 
intersection, difference, and excluslve-OR; It can also determine whether a 
given point or rectangle intersects a given region, and so on. There is of 
course a set of graphic operations on regions to draw them on the screen. 

E.4 Graphic Entities 

Coordinate planes, points, rectangles, and regions are all good mathematical 
models, but they aren't really graphic elements—they don't have a direct 
physical appearance. S(»ine grajphic entities that do have a direct graphic 
interpretation are the bit Image, bitmaps pattern and cursor. This section 
describes the data structure of these graphic entities and how they relate to 
the mathematical constructs described above. 

E.4wl ine Bit Image 

A bit image is a collection of bits In memory which have a rectilinear 
representation. Take a collection of words in memory and lay them end to 
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end so that Dlt 15 of the lowest-numbered word Is on the left and bit of 
the highest-numbered word is on the far right. Then take this array of bits 
and divide It, on word boundaries, into a nurriber of equal-size rows, stack 
these rows vertically so that the first row is on the top and the last row is on 
the bottom. The result is a matrix like the one shown in Figure E-5~rows 
and columns of bits, with each row containing the same number of bytes. The 
number of bytes in each row of the bit Image is called the row wiam of that 
image. 




Row width 
is 8 bvtes 



Figure E-5 
A Bit Image 

A bit image can be stored In any static or dynamic variable, and can be of 
any length that is a multiple of the row width. 

The Lisa screen itself Is one large visible bit image. There are 32,760 bytes of 
memory that are displayed as a matrix of 262,080 pixels on the screen, each 
bit corresponding to one pixel. If a bit's value is 0, Its pixel is white; If the 
bit's value is i, the pixel Is black. 

The screen is 364 pixels tall and 720 pixels wide, and the row width of Its bit 
image is 90 bytes. Each pixel on the screen is one and a half times taller 
than It Is wide, meaning a rectangle 30 pixels wide by 20 tall looks square, 
and a 30 by 20 oval looks circular. There are 90 pixels per inch horizontally, 
and 60 per Inch vertically. 
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NOTE 



Since each pixel on the screen represents one oil in a bit image, 
wherever this appendix says "bit", you can substitute "pixel" If the bit 
image Is the Lisa screen. Likewise, this appendix often refers to pixels 
on the screen where the discussion applies equally to bits In an 
off-screen bit Image. 



E.4.2 The Bitmap 

When you combine the physical entity of a bit image with the conceptual 
entities of the coordinate plane and rectangle, you get a bitmap. A bitmap 
has three parts: a pointer to a bit Image, the row width (in bytes) of that 
Image, and a boundary rectangle which gives the bitmap both its dimensions 
and a coordinate system. Notice that a bitmap does not actually include the 
bits themselves: It points to them. 

There can be several bitmaps pointing to the same bit Image, each Imposing a 
different coordinate system on it This important feature is explained more 
fully In Section E.6, Coordinates In GrafPorts. 

As shown In Figure E-6, the data structure of a bitmap Is as follows: 

type Bltnap = record 

DaseAddr: QOPtr; 
roi6ytes: Integer; 
bounds: Rect 
end; 
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Figure E-6 
A Bitmap 
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The t)aseAd(ir field Is a pointer to the beginning of the bit Image In nnemory^ 
and the rowBytes field Is the number of bytes In each row of the Image. Both 
of these should always be even: a bitmap should always begin on a word 
boundary and contain an integral number of words In each row. 

The bounds field is a boundary rectangle that both encloses the active area of 
the bit Image and Imposes a coordinate system on It The relationship 
between the boundary rectangle and the bit image in a bitmap is simple yet 
very Important First, a few general rules: 

• Bits in a bit image fall between points on the coordinate plane. 

• A rectangle divides a bit Image into two sets of bits: those bits inside the 
rect£»igle and those outside the rectangle. 

• A rectangle that is H points wide and V points tall encloses exactly 
(H-1) * (V-1) bits. 

The top left comer of the boundary rectangle is aligned around the first bit In 
the bit image. The width of the rectangle determines how many bits of one 
row are logically owned by the bitmap; the relationship 

8 * map.rovBytes >= map. bounds. right-map. bounds. left 

must always be true. The height of the rectangle determines how many rows 
of the Image are logically owned by the bitmap. To ensure that the number 
of bits in the logical bitmap Is not larger than the number of bits in the bit 
Image, the bit Image must be at least as big as 

(map.bounds .bottom-map.bounds .top)«map.roiiBytes 

Normally, the boundary rectangle completely encloses the bit image: the width 
of the boundary rectangle Is equal to the number of bits In one row of the 
Image, and the height of the rectangle Is equal to the number of rows In the 
Image. If the rectangle Is smaller than the dimensions of the Image, the least 
significant bits in each row, as well as the last rows In the Image, are not 
affected by any operations on the bitmap. 

The bitmap also imposes a coordinate system on the Image. Because bits fall 
between coordinate points, the coordinate system assigns Integer values to the 
lines that border and separate bits, not to the bit positions themselves. For 
example. If a bitmap is assigned the boundary rectangle with comers (10,-8) 
and (34,8), the bottom right bit In the Image will be between horizontal 
coordinates 33 and 34, and between vertical coordinates 7 and 8 (see Figure 
E-7). 
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Figure E-7 
Coordinates and Bitmaps 



E.43 Patterns 

A pattern Is a 64-blt Image, organized as an 8-by-8-bit rectangle, which is 
used to define a repeating design (such as stripes) or tone (such as gray). 
Patterns can be used to draw lines and shapes or to fill areas on the screen. 

When a pattern is drawn. It is aligned such that adjacent areas of the same 
pattern in the same graphics port will blend with each other into a contin- 
uous, coordinated pattern. QuickDraw provides the predefined patterns wTiite, 
black, gray, itGray, and dkGray. Any other 64-bit variable or constant can be 
used as a pattern, too. The data type definition for a pattern is as follows: 

type Pattern = packed array [0..7] of 0..255; 

The row width of a pattern Is i byte. 

E.4.4 Cmraon 

A cursor is a small image that appears on the screen and is controlled by the 
mouse. (It appean only on the screen, and never in an off-screen bit image.) 



A cursor is defined as a 256-blt Image, a 16-by-16-bit rectangle, 
width of a cursor is 2 bytes. Figure E-8 illustrates four cursors. 



The row 
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Figure E-8 
CXirsors 

A cursor has three fields: a 16-word data field that contains the Image Itself^ 
a 16-word mask field that contains Information alDout the screen appearance 
of each bit of the cursor^ and a hotspot point that aligns the cunor with the 
position of the mouse. 

type Cursor = record 

data: array [0..153 of Integer; 
mask: array [0..15] of Integer; 
hotspot: Point 
end; 

The data for the cursor must begin on a word boundary. 

The cursor appears on the screen as a i6-by-i6-blt rectangle. The appear- 
ance of each bit of the rectangle is determined by the corresponding bits in 
the data and mask and, if the mask bit Is 0, by the pixel "under" the cursor 
(the one already on the screen In the same position as this bit of the cursor) 
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Resulting pixel on screen 

White 

Black 

same as pixel under cursor 

Inverse of pixel under cursor 

Notice that If all mask bits are o, the cursor is completely transparent, in 
that the image under the cursor can still be viewed: pixels under the white 
part of the cursor appear unchanged, while under the black part of the cursor, 
black pixels show through as white. 

The hotspot aligns a point In the image (not a bit, a point!) with the mouse 
position. Imagine the rectangle with corners (0J3) and (16,16) framing the 
Image, as in each of the exemples in Figure E-8; the hotspot is defined in this 
coordinate system, A hotspot of (0,0) is at the top left of the image. For the 
arrow in Figure E-8 to point to the mouse position, (0,0) would be Its hotspot 
A hotspot of (8,8) Is In the exact center of the image; the center of the plus 
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sign or oval in Figure E-8 would coincide with the mouse position if (8^) were 
the hotspot for that cursor. Similarly^ the hotspot for the pointing hand would 
De (16.9)1 

Whenever you move the mouse, the low-level interrupt-drlven mouse routines 
move the cursor's hotspot to be aligned with the new mouse position. 

QuickDraw supplies a predefined arrow cursor, an arrow pointing north- 
northwest 

Refer to Appendix F, Hardware Interface, for more information on the mouse 
and cursor control. 

E.5 The Drawing Environment: GrafPort 

A grafPort is a complete drawing environment that defines how and where 
graphic operations will have their effect. It contains all the information 
about one Instance of graphic output that is kept separate from all other 
Instances. You can have many grafPorts open at once, and each one will have 
its own coordinate system, drawing pattern, background pattern, pen size and 
location, character font and style, and bitmap in which drawing takes place. 
You can instantly switch from one port to another. GrafPorts are the 
structures on which a program builds windows, which are fundamental to the 
Lisa's "overlapping windows" user interface. 

A grafPort is a dynamic data structure, defined as follows: 



type GrafPtr = *GrafPort; 




GrafPort = record 




device: 


Integer; 


portBlts: 


BltMap; 


portRect: 


Rect; 


vlsRgn: 


RgnHandle; 


cllpRgn: 


RgnHandle; 


dkPat: 


Pattera* 


flllPat: 


Pattenv 


pnLoc: 


Point; 


pnSize: 


Point; 


pnhode: 


Integer; 


pnPat: 


Pattern; 


pnvis: 


integer; 


txFont: 


integer; 


txFace: 


Style; 


txhode: 


integer; 


txSlze: 


integer; 


spExtra: 


longint; 


fgColor: 


longint; 


bkColor: 


longint; 


colrBlt: 


int^eger; 


patstretch: 


integer; 


plcSave: 


QOHandle; 
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rgnsave: QOHandle; 

polySave: QOHandle; 

graifProcs: tjOProcsPtr 
end; 

All QuickDraw operations refer to grafPorts via grafPtrs. You create a 
grafPort with the Pascal procedure new and use the resulting pointer In calls 
to QuickDraw, You could, of course, declare a static variable of type 
GrafPort, and obtain a pointer to that static structure (with the © operator), 
but as most grafPorts will be used dynamically, their data structures should be 
dynamic also. 

NOTE 

You can access all fields and subflelds of a grafPort normally, but you 
should not store new values directly into them. QuickDraw has 
procedures for altering all fields of a grafPort, and using these 
procedures ensures that changing a grafPort produces no unusual side 
effects. 



The device field of a grafPort is the number of the logical output device that 
the grafPort will be using. QuickDraw uses this information, since there are 
physical differences in the same logical font for different output devices. The 
default device number Is 0, for the Lisa screea 

The portBlts field is the bitmap that points to the bit image to be used by the 
grafPort. All drawing that is done in this grafPort will take place In this bit 
image. The default bitmap uses the entire Lisa screen as its bit image, with 
rowBytes of 90 and a boundary rectangle of (0,0,720,364). The bitmap may be 
changed to indicate a different structure in memory: all graphics procedures 
work in exactly the same way regardless of whether their effects are visible 
on the screea A program can, for example, prepare an image to be printed 
on a printer without ever displaying the image on the screen, or develop a 
picture in an off-screen bitmap before transferring it to the screen. By 
altering the coordinates of the portBitsixxjnds rectangle, you can change the 
coordinate system of the grafPort; with a QuickDraw procedure call, you can 
set an arbitrary coordinate system for each grafPort, even if the different 
grafPorts all use the seme bit Image (e.g., the full screen). 

The portRect field Is a rectangle that defines a subset of the bitmap for use 
by the grafPort Its coordinates are In the system defined by the 
portBltsixxmds rectangle. All drawing done by the application occun Inside 
this rectangle. The portRect usually defines the "writable" interior area of a 
window, document, or other object on the screen. The default portRect Is the 
entire screen. 

The visRgn field Indicates the region that is actually visible on the screen, it 
is reserved for use by future software, and should be treated as read-only. 
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The default visRgn Is set to the portRect 

The cIlpRgn is an art)ltrary region that the application can use to limit 
drawing to any region within the portRect It for example^ you want to draw 
a half circle on the screen, you can set the clipRgn to half the square that 
would enclose the whole circle, and go ahead and draw the whole circle. Only 
the half within the cllpRgn will actually be drawn in the grafPort. The 
default ClipRgn is set arbitrarily large, and you have full control over its 
setting. Notice that unlike the vlsRgn, the clipRgn affects the image even if 
it is not displayed on the screen. 

Figure E-9 Illustrates a typical bitmap (as defined by portBlts), portRect 
vlsRga and clipRgn. 
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Figure E-9 
GrafPort Regions 

The bkPat aid flllPat fields of a grafPort contain patterns used by certain 
QuickDraw routines. BkPat is the "background" pattern that is used when an 
area is erased or when bits are scrolled out of it When asked to fill an area 
with a specified pattern, QuickDraw stores the given pattern in the flllPat 
field and then calls a low-level drawing routine which gets the pattern from 
that field. The various graphic operations are discussed in detail later in the 
descriptions of individual QuickDraw routines. 

Of the next ten fields, the first five determine characteristics of the graphics 
pen, described in section E.5.1, and the last five determine characteristics of 
any text that may be drawn, described in Section E.5.2. 

The fgcolor, bkcoior, and coliBit fields contain values related to drawing in 
color, a capability that will be available in the future when Apple supports 
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color output devices for the Lisa. FgColor is the grafPort's foreground color 
and bkColor Is its background color. ColiBit tells the color imaging software 
which plane of the color picture to draw into. For more information, see 
section E.7.2, Drawing in Color. 

The patstretch field is used during output to a printer to expand patterns if 
necessary. The application should not change its value. 

The picSave, rgnSave, and polySave fields reflect the state of picture, region, 
and polygon definition, respectively. To define a region, for example, you 
"open" it, call routines that draw it, and then "close" it. If no region is open, 
rgnSave contains nil- otherwise, it contains a handle to information related to 
the region definition. The application should not be concerned about exactly 
what information the handle leads to; you may, however, save the current 
value of rgnSave, set the field to nil to disable the region definition, and later 
restore it to the saved value to resume the region definition. The plcSave 
and polySave fields work similarly for pictures and polygons. 

Finally, the grafProcs field may point to a special data structure that the 
application stores into if it wants to customize QuickDraw drawing procedures 
or use QuickDraw in other advanced, highly specialized ways. (For more 
information, see Section E.IO, Customizing QuickDraw Operations.) If 
grafProcs Is nil, QuickDraw responds In the standard ways described in this 
appendix. 

E3.1 Pen Characteristics 

The pnLoc, pnsize, pnMode, pnPat and pnvis fields of a grafPort deal with the 
graphics pen. Each grafPort has one and only one graphics pen, which Is used 
for drawing lines, shapes, and text As illustrated in Figure E-10, the pen has 
four characteristics: a locatloa a size, a drawing mode, and a drawing pattern 
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Figure E-10 
A Graphics Pen 

The pen location (pnLoc) is a point in the coordinate system of the grafPort, 
and is where GjuickDraw will begin drawing the next line, shape, or character. 
It can be anywhere on the coordinate plane: there are no restrictions on the 
movement or placement of the pen. Remember that the pen location is a 
point on the coordinate plane, not a pixel in a bit image! 

The pen is rectangular in shape, and has a user-definable width and height 
(pnslze). The default size is a l-by-1-bit rectangle; the width and height can 
range from (0,0) to (3276732767). If either the pen width or the pen height is 
less than l, the pen will not draw on the screen. 

• The pen appears as a rectangle with Its top left comer at the pen 
location; it hangs below and to the right of the pen location. 

The pnMode and pnPat fields of a grafport determine how the bits under the 
pen are affected when lines or shapes are drawn. The pnPat Is a pattern that 
is used as the "Ink" In the pen. This pattern, like all other patterns drawn In 
the grafPort, Is always aligned with the port's coordinate system: the top left 
corner of the pattern Is aligned with the top left comer of the portRect, so 
that adjacent areas of the same pattern will blend Into a continuous, 
coordinated pattern. Five patterns are predefined (white, black, and three 
shades of gray); you can also create your own pattern and use It as the pnPat 
(A utility procedure, called StuffHex, allows you to fill patterns easily.) 
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The pnMode field determines how the pen pattern Is to affect what's already 
on the bitmap when lines or shapes are drawn. When the pen draws^ 
QuickDraw first determines what bits of the bitmap will be affected and finds 
their corresponding bits in the pattern. It then does a bit-by-bit evaluation 
based on the pen mode^ which specifies one of eight boolean operations to 
perform. The resulting bit is placed into its proper place in the bitmap. The 
pen modes are described in section E.7.1, Transfer Modes. 

The pnVls field determines the pen's visibility, that is, whether it draws on the 
screen. For more information, see the descriptions of HidePen and ShowPen 
in Section E.9.3, Pen and Line-Drawing Routines. 

E.5.2 Text Characteristics 

The txFont, txFace, txMode, txsize, and spExtra fields of a grafPort determine 
how text will be drawn—the font, style, and size of characters and how they 
win be placed on the bitmap. 

QuickDraw can draw characters as quickly and easily as It draws lines and 
shapes, and in many prepared fonts. Figure E-11 shows two QuickDraw 
characters and some terms you should become familiar with. 

Qscent line 



ascent 



descent 



k-/ 



character 
h- width -» 



D 



^^ — base line 



descent line 



Figure E-ll 
QuickDraw Characters 

QuickDraw can display characters In any size, as well as boldfaced. Italicized, 
outlined, or shadowed, all without changing fonts. It can also underline the 
characters, or draw them closer together or farther apart 

The ixFont field Is a font number that Identifies the character font to be used 
In the grafPort. The font number represents the system font, and is the 
default established by openPort. The unit QDSupport (listed in section E.15) 
includes definitions of other available font numbers. 

A character font is defined as a collection of bit images: these images make 
up the Individual characters of the font. The characters can be of unequal 
widths, and they're not restricted to their "cells": the lower curl of a 
lowercase j, for example, can stretch back under the previous character 
(typographers call this kemJng\ A font can consist of up to 256 distinct 
characters, yet not all characters need be defined In a single font. Each font 
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contains a missing symool to De drawn In case of a request to draw a 
character that is missing from the font 

The txFace field controls the appearance of the font with values from the set 
defined by the Style data type: 

type styieltem » (bold Italia underline^ outline^ snadov^ 
condense^ extend); 

style = set of stylelteRU 

You can apply these either alone or In combination (see Figure E-12). Most 
combinations usually look good only for large fonts. 

Normal Characters 
Bold Characters 

italic Characters 
Underlined Characters xyi 



Condensed Characters 
Extended Characters 

. . . and in other fonis, loo! 

Figure E-12 
cnaracter Styles 

If you specify boid^ each character is repeatedly drawn one bit to the right an 
appropriate number of times for extra thickness. 

Italic adds an italic slant to the characters. Character bits above the base 
line are skewed right; bits below the base line are skewed left 

underline draws a line below the base line of the characters. If part of a 
character descends below the base line (as "y" in Figure E-12), the underline Is 
not drawn through the pixel on either side of the descending part. 

You may specify either outline or shadow. Outline makes a hollow, outlined 
character rather than a solid one. With shadow, not only is the character 
hollow and outlined, but the outline is thickened below and to the right of the 
character to achieve the effect of a shadow. If you specify bold along with 
outline or shadow, Vdb hollow part of Vne character Is widened. 
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Condense and extend affect tne horizontal distance between all characters, 
including spaces. Condense decreases the distance between characters and 
extend Increases it, by an amount which QuickDraw determines is appropriate. 

The txMode field controls the way characters are placed on a bit Image. It 
functions much llKe a pnMode: when a character is drawn, QuickDraw 
determines which bits of the bit image will be affected, does a bit-by-bit 
comparison based on the mode, and stores the resulting bits Into the bit 
Image. These nnodes are described in Section E.7.1, Transfer Modes. Only 
three of them— srcQr, srcXor, and srcBlc—should be used for drawing text 

^\\^ txSlze field specifies the type size for the font, in points (where "point" 
here is a typographical term meaning approximately 1/72 inch). Any size may 
be specified. If QuickDraw does not have the font in a specified size. It will 
scale a size it does have as necessary to produce the size desired. A value of 
in this field directs QuickDraw to choose the size from among those It has 
for the font; It will choose whichever size Is closest to the system font size. 

Finally, the spExtra field Is useful when a line of characters Is to be drawn 
Justified such that it Is aligned with both a left and a right margin (sometimes 
called "full justification"). SpExtra Is the number of pixels by which each 
space character should be widened to fill out the line. 

E.6 Coordinates In GrafPorts 

Each grafPort has Its own iccal coordinate system. All fields In the grafPort 
are expressed in these coordinates, and all calculations and actions performed 
in QuickDraw use the local coordinate system of the currently selected port. 

Two things are important to remember: 

• Each grafPort maps a portion of the coordinate plane into a similarly- 
sized portion of a bit image. 

• The portBltsiJounds rectangle defines the local coordinates for a grafPort. 

The top left comer of portBlt$.bounds Is always aligned around the first bit in 
the bit Image; the coordinates of that corner "anchor" a point on the grid to 
that bit In the bit Image. This forms a common reference point for multiple 
grafPorts using the same bit image (such as the screen^ Given a 
portBits.bounds rectangle for each port, you know that their top left comers 
coincide. 

The interrelationship between the poitBitsi)ounds and portRect rectangles Is 
very Important. As the portBltsJxxiids rectangle establishes a coordinate 
system for the port, the portRect rectangle Indicates the section of the 
coordinate plane (and thus the bit image) that will be used for drawing. The 
portRect usually falls inside the portBits.t»und$ rectangle, but it's not required 
to do so. 

When a new grafPort is created. Its bitmap is set to point to the entire Lisa 
screen, and both the portBitsJtxiunds and the portRect rectangles are set to 
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720-by-364-Dit rectangles^ with the point (0^0) at tne top left corner of the 
screen. 

You can redefine the local coordinates of the top left corner of the grafPort's 
portRect, using the SetOrigln procedure. This changes the local coordinate 
system of the grafPort^ recalculating the coordinates of all points in the 
grafPort to De relative to the new comer coordinates. For example, consider 
these procedure calls: 

SetPort(ganiePort); 
Set0rigin(40,80); 

The call to SetPort sets the current grafPort to gamePort; the call to 
SetOrigin changes the local coordinates of the top left corner of that port's 
portRect to (40^0) (see Figure E-13). 
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Figure E-13 
Changing Local Coordinates 

This recalculates the coordinate components of the following elements; 

garaePort^.portBlts.Dounds gamePort*. portRect 

gaiiiePort*.vlsRgn 

These elements are always kept "in sync", so that all calculations, compari- 
sons, or operations that seem right, work right. 

Notice that when the local coordinates of a grafPort are offset, the visRgn of 
that port is offset also, but the clipRgn is not. A good way to think of it is 
that if a document is being shown inside a grafPort, the document "sticks" to 
the coordinate system, and the port's structure "sticks" to the screen. 
Suppose, for example, that the vlsRgn and clipRgn in Figure E-13 before 
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SetQrlgln are the same as the portRect^ and a document is being shown. After 
the SetOrigin calL the top left comer of the cllpRgn Is still (95420)^ but this 
location has moved down and to the right, and the location of the pen within 
the document has similarly moved. The locations of portBltsiJOunds, portRect 
and vlsRgn did not change; their coordinates were offset as always, the top 
left comer of portBitsiwunds remains aligned around the first bit in the bit 
image (the first pixel on the screen^ 

If you are moving, comparing, or otherwise dealing with mathematical items in 
different grafPorts (for example, finding the intersection of two regions in two 
different grafPorts), you must adjust to a common coordinate system before 
you perform the operation. A QuickDraw procedure, LocalToGlobal, lets you 
convert a point's local coordinates to a gJc^^al system where the top left 
corner of the bit image is (0,0); by converting the various local coordinates to 
global coordinates, you can compare and mix them with confidence. For more 
information, see the description of this procedure in Section E.9.17, 
Calculations with Points. 

E.7 General Discussion of Drawing 

Drawing occurs: 

• Always Inside a grafPort, in the bit image and coordinate system defined 
by the grafPort's bitmap. 

• Always within the intersection of the grafPort's portBlts.bounds and 
portRect, and clipped to Its visRgn and clipRgn. 

• Always at the grafPort's pen location. 

• Usually with the grafPort's pen size, pattern, and mode. 

With QuickDraw procedures, you can draw lines, shapes, and text. Shapes 
Include rectangles, ovals, rounded-corner rectangles, wedge-shaped sections of 
ovals, regions, and polygons. 

Lines are defined by two points: the current pen location and a destination 
location. When drawing a line, QuickDraw moves the top left corner of the 
pen along the mathematical trajectory from the current location to the 
destination. The pen hangs below and to the right of the trajectory (see 
Figure E-14). 
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Figure E-14 
Drawing Lines 

NOTE 



No mathematical element (such as the pen location) Is ever affected by 
clipping; clipping only determines what appears where in the bit image. 
If you draw a line to a location outside your grafPort, the pen location 
will move there, but only the portion of the line that is inside the port 
will actually be drawn. This is true for all drawing procedures. 



Rectangles, ovals, and rounded-comer rectangles are defined by two comer 
points. The shapes always appear inside the mathematical rectangle defined 
by the two points. A region is defined in a more complex manner, but also 
appean only within the rectangle enclosing it. Remember, these enclosing 
rectangles have Infinitely thin borders and are not visible on the screen. 

As illustrated in Figure E-15, shapes may be drawn either sella (filled in with 
a pattern) or framed (outlined and hollow). 
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Figure E-15 
Solid Shapes and Framed Shapes 

In the case of framed shapes, the outline appears completely within the 
enclosing rectangle—with one exception— and the vertical and horizontal 
thickness of the outline is determined by the pen size. The exception is 
polygons, as discussed in section E.8.2, Polygons. 

The pen pattern is used to fill in the bits that are affected by the drawing 
operation. The pen mode defines how those bits are to be affected by 
directing QuickDraw to apply one of eight boolean operations to the bits in 
the shape and the corresponding pixels on the screen. 

Text drawing does not use the pnsize, pnPat, or pnMode, but it does use the 
pnLoa Each character is placed to the right of the current pen location, with 
the left end of its base line at the pen's location. The pen is moved to the 
right to the location where It will draw the next character. No wrap or 
carriage return is performed automatically. 

The method QuickDraw uses In placing text Is controlled by a mode similar to 
the pen mode. This Is explained in Section E.7.1, Transfer Modes. Clipping of 
text Is performed in exactly the same manner as all other clipping in 
GjuickDraw. 

E.7.1 Transfer Modes 

When lines or shapes are drawn, the pnMode field of the grafPort determines 
how the drawing is to appear in the port's bit image; similarly, the txMode 
field determines how text is to appear. There Is also a QuickDraw procedure 
that transfers a bit image from one bitmap to another, and this procedure has 
a mode parameter that determines the appearance of the result. In all these 
cases, the mode, called a transfer mode, specifies one of eight boolean 
operations: for each bit in the Item to be drawn, QuickDraw finds the 
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corresponding bit in the destination bit Image^ performs the boolean operation 
on the pair of bits, and stores the resulting bit into the bit Image. 

There are two types of transfer mode: 

• Pattern transfer mocfes, for drawing lines or shapes with a pattern. 

• Source transfer modei^ for drawing text or transferring any bit image 
between two bitmaps. 

For each type of mode, there are four basic operations— Copy, or, Xor, and 
Bio. The Copy operation simply replaces the pixels in the destination with 
the pixels In the pattern or source, "painting" over the destination without 
regard for what is already there. The Or, Xor, and Blc operations leave the 
destination pixels under the white part of the pattern or source unchanged, 
and differ in how they affect the pixels under the black part: Or replaces 
those pixels with black pixels, thus "overlaying" the destination with the black 
part of the pattern or source; Xor Inverts the pixels under the black part; and 
Blc erases them to white. 

Each of the basic operations has a variant in which every pixel in the pattern 
or source is inverted before the operation is performed, giving eight 
operations in all. Each mode is defined by name as a constant In QuickDraw 
(see Figure E-16). 






pattern or source destination 

"Paint" "Overlay" "Invert" "Erase" 



■ 




patCopy patOr patXor patBic 
srcCopy srcOr srcXor srcBic 






notPatCojuy notPatOr notPatXor notPalBlc 
notSrcCopy notSrcOr notSrcXor notSrcBic 

Figure E-16 
Transfer Modes 
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If black pixel in If white pixel in 
pattern or source pattern or source 



patCopy 
patOr 
patxor 
patBic 

notPatcopy 
notPator 
notPatxor 
notPatBic 


srcCopy 
srcOr 
srcxor 
srcBic 

notsrccopy 
notSrcQr 
notsrcxor 
notSrcBic 


Force black 
Force black 
Invert 
Force white 

Force white 
Leave alone 
Leave alone 
Leave alone 


Force white 
Leave alone 
Leave alone 
Leave alone 

Force black 
Force black 
Invert 
Force white 



E.7.2 Drawing in Color 

Currently you can only look at GjuickDraw output on a black-and-white screen 
or printer. Eventually^ however, Apple will support color output devices. If 
you want to set up your application now to produce color output in the future, 
you can do so by using QuickDraw procedures to set the foreground color and 
the background color. Eight standard colors may be specified with the 
following predefined constants: blackColor^ whiteColor, redColor, greenColor^ 
bluecolor, cyancolor, magentacolor, and yellowcoior. initially, the foreground 
color is blackColor and the background color is whiteColor. If you specify a 
color other than whlteColor, it will appear as black on a black-and-white 
output device. 

To apply the table above (in Section E.7.1) to drawing in color, make the 
following translation: where the table shows "Force black", read "Force 
foreground color", and where it shows "Force white", read "Force background 
color". When you eventually receive the color output device, you'll find out 
the effect of inverting a color on It. 

NOTE 

QuickDraw can support output devices that have up to 32 bits of color 
information per pixel. A color picture may be thought of, then, as 
having up to 32 planes. At any one time, QuickDraw draws into only 
one of these planes. A QuickDraw routine called by the color-imaging 
software specifies which plane. 

E.8 Pictures and Polygons 

QuickDraw lets you save a sequence of drawing commands and "play them 
back" later with a single procedure call. There are two such mechanisms: one 
for drawing any picture to scale in a destination rectangle that you specify, 
and another for drawing polygons In all the ways you can draw other shapes In 
QuickDraw. 



E-28 



Pascal Reference Manual QuickDraw 



E.8.1 Pictures 

A picture in QuickDraw is a transcript of calls to routines which draw 
somethlng~anythlng~on a bitmap. Pictures make it easy for one program to 
draw something defined in another program^ with great flexibility and without 
knowing the details about whafs being drawn. 

For each picture you define, you specify a rectangle that surrounds the 
picture; this rectaigle is called the picture frame When you later call the 
procedure that draws the saved picture, you supply a destination rectangle, 
and QuickDraw scales the picture so that its frame is completely aligned with 
the destination rectangle. Thus, the picture may be expanded or shrunk to fit 
its destination rectangle. For example, if the picture is a circle inside a 
square picture frame, and the destination rectangle is not square, the picture 
is drawn as an oval. 

since a picture may Include any sequence of drawing commands, its data 
structure Is a variable-length entity. It consists of two fixed fields followed 
tii a variable-length data field: 

type Picture = record 

plcSize: integer; 
plcFrame: Rect; 
{picture definition data} 
end; 

The picSize field contains the size, in bytes, of the picture variable. The 
plcFrame field is the picture frame which surrounds the picture and gives a 
frame of reference for scaling when the picture is drawn. The rest of the 
structure contains a compact representation of the drawing commands that 
define the picture. 

All pictures are accessed through handles, which point to one master pointer 
which in turn points to the picture. 

type PlcPtr = "Picture; 
PlcHandle = TicPtr; 

To define a picture, you call a QuickDraw function that returns a picture 
handle and then call the routines that draw the picture. There is a procedure 
to call when you've finished defining the picture, and another for when you're 
done with the picture altogether. 

QuickDraw also allows you to intersperse picture comments with the 
definition of a picture. These comments, which do not affect the picture's 
appearance, may be used to provide additional Information about the picture 
when it's played back. This is especially valuable when pictures are 
transmitted from one application to another. There are two standard types of 



E-29 



Pascal Reference Manual QuickDraw 



comnnent whlch^ like parentneses. serve tx) group drawing commands together 
(such as all the commands that draw a particular part of a picture) 

const plcLParen = 0; 
plcRParen = 1; 

The application defining the picture can use these standard comments as well 
as comments of its own design. 

To Include a comment in the definition of a picture^ the application calls a 
QuickDraw procedure that specifies the comment with three parameters: the 
comrment kind, which identifies the type of comment; a handle to additional 
data if desired; and the size of the additional data, if any. When playing back 
a picture, QuickDraw passes any comments in the picture's definition to a 
low-level procedure accessed indirectly through the grafProcs field of the 
grafPort (see Section E.lO, Customizing QuickDraw Operations, for more 
Information). To process comments, the application must include a procedure 
to do the processing and store a pointer to it in the data structure pointed to 
by the grafProcs field. 

NOTE 

The standard low-level procedure for processing picture conrwments 
simply ignores all comments. 

E.8.2 Polygons 

Polygons are similar to pictures in that you define them by a sequence of 
calls to QuickDraw routines. They are also similar to other shapes that 
QuickDraw knows about, since there is a set of procedures for performing 
graphic operations and calculations on them. 

A polygon is simply any sequence of connected lines (see Figure E-17). you 
define a polygon by moving to the starting point of the polygon and drawing 
lines from there to the next point, from that point to the next, and so on. 




Figure E-17 
Polygons 
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The data structure for a polygon \% a variable-length entity. It consists of 
two fixed fields followed by a variable-length array: 

type Polygon = record 

polySlze: integer; 
polyOBox: Rect; 
polyPolnts: array [0..0] of Point 
end; 

The polySlze field contains the size, in bytes, of the polygon variable. The 
polyBBox field Is a rectangle which just encloses the entire polygon. The 
polyPolnts array expands as necessary to contain the points of the polygon— 
the starting point followed by each successive point to which a line Is drawn. 

Like pictures and regions, polygons are accessed through handles. 

type PolyPtr = "Polygon; 
PolyHandle = "PolyPtr; 

To define a polygon, you call a QuickDraw function that returns a polygon 
handle and then form the poiyyxi by calling procedures that draw lines. You 
call a procedure when you've finished defining the polygon, and another when 
you're done with the polygon altogether. 

Just as for other shapes that GjulckDraw knows about, there Is a set of 
graphic operations on polygons to draw them on the screen. QuickDraw draws 
a polygon ta^ moving to the starting point and then drawing lines to the 
remaining points In succession, just as when the routines were called to define 
the polygon. In this sense It "plays back" those routine calls. As a result, 
polygons are not treated exactly the same as other QuickDraw shapes. For 
example, the procedure that frames a polygon draws outside the actual 
boundary of the polygon, because QuickDraw ilne-drawlng routines draw below 
and to the right of the pen location. The procedures Uiat fill a polygon with 
a pattern, however, stay within the boundary of the polygon; they also add an 
additional line between the ending point and the starting point If those points 
are not the same, to complete the shape. 

There Is also a difference In the way QuickDraw scales a polygon and a 
slmllarly-shqDed region If It's being drawn as part of a picture: when 
stretched, a slanted line Is drawn more smoothly If It's part of a polygon 
rather than a region. You may find It helpful to keep In mind the conceptual 
difference between polygons and regions: a polygon Is treated more as a 
continuous shape, a region more as a set of bits. 

E.9 QuickOiaw Routines 

This section describes all the procedures and functions In QuickDraw, their 
parameters, and their operation. They are presented In their Pascal form; for 
Information on using them from assembly language, see Section E.11, Using 
QuickDraw from Assembly Language. Note that the actual procedure and 
function declarations are given here, rather than the BNF notation or syntax 
diagrams used elsewhere In this manual. 
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E.9.1 GrafPort Routines 

Procedure initGraf (glotelPtr: QDPtr); 

inllGraf initializes QuickDraw. It is called by the QDSupport unit's QDlnit 
routine; you need not call it again. It initializes the QuickDraw global 
variables listed below. 



variable 


Type 


Initial settina 


thePort 


GrafPtr 


mi 


white 


Pattern 


all-white pattern 


black 


Pattern 


all-black pattern 


gray 


Pattern 


50% gray pattern 


ItGray 


Pattern 


25% gray pattern 


dkGray 


Pattern 


75% gray pattern 


arrow 


Cursor 


pointing arrow cursor 


screenBlts 


Bltnap 


Lisa screea (0^0720^64) 


randSeed 


longlnt 


1 



The globalPtr parameter tells QuickDraw where to store its global variables, 
beginning with thePort From Pascal programs, this parameter should always 
be set to sthePort; assembly-language programmers may choose any locatioa 
as long as it can accommodate the number of bytes specified by GRAFSIZE in 
GRAFTYPES.TEXT (see Section E.ii, using QuickDraw from Assembly 
Language). 

NOTE 

To initialize the cursor, call Initcursor (described In Section E.9.2, 
Cursor-Handling Routines). 



Procedure openPort (gp: GrafPtr); 

openPort allocates space for the given grafPort's vlsRgn and cUpRgn^ 
initializes the fields of the grafPort as indicated below, and makes the 
grafport the current port (see setPort, below). You must call OpenPort before 
using any grafPort; first create a grafPtr with new, then use that grafPtr in 
the OpenPort call. 
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Field 


Type 


Initial settlna 


device 


Integer 


(Lisa screen) 


portBlts 


Bltnap 


screenBlts (see inltGraf) 


portRect 


Rect 


screenBltsixxjnds (0^720^64) 


vlsRgn 


RgnHandle 


handle to the rectangular region (0^1720^64) 


clipRgn 


RgnHandle 


handle to the rectangular region 
(-30000, -30000. 30000, 30000) 


bkPat 


Pattern 


white 


flllPat 


Pattern 


black 


pnLoc 


Point 


(0^) 


pnSlze 


Point 


(1.1) 


pnnode 


Integer 


patCopy 


pnPat 


Pattern 


black 


pnVis 


Integer 


(visible) 


txFont 


Integer 


(system font) 


t>tf^ace 


Style 


normal 


txMode 


Integer 


srcor 


txsize 


integer 


(QuickDraw decides) 


spExtra 


longlnt 





fgcolor 


longint 


blackColor 


bkcolor 


longlnt 


whltecolor 


colrBit 


integer 





patstretch 


Integer 





picSave 


goHandle 


nil 


rgnsave 


QDHandie 


nil 


polySave 


QDHandle 


nil 


grafProcs 


QDProcsPtr 


nil 



Procedure InitPort (gp: GrafPtr); 

Given a pointer to a grafPort that has been opened with openPort, inltPort 
reinitializes the fields of the grafPort and makes it the current port (if it's 
not already)L 

NOTE 

InitPort does everything OpenPort does except allocate space for the 
visRgn and clipR9i 



Procedure closePort (gp: GrafPtr); 

ClosePort deallocates the space occupied by the given grafPort's visRgn and 
clipRgn. When you are completely through with a grafPort, call this 
procedure. 
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If you do not call ClosePort before disposing of the grafPort, the 
memory used by the visRgn and clipRgn will be unrecoverable. 

After calling ClosePort, be sure not to use any copies of the vlsRgn or 
ClipRgn handles that you may have made. 



Procedure setPort (gp: GrafPtr); 

setPort sets the grafPort indicated by gp to be the current port. The global 
pointer thePort always points to the current port. All QuickDraw drawing 
routines affect the bitmap tnePort"4X)rtBlts and use the local coordinate 
system of thePorl". Note that OpenPort and InitPort do a SetPort to the 
given port. 

WARNING 

Never do a SetPort to a port that has not been opened with OpenPort. 

Each port possesses its own pen and text characteristics which remain 
unchanged when the port is not selected as the current port. 

Procedure GetPort (var gp: GrafPtr); 

GelPort returns a pointer to the current grafPort. If you have a program that 
draws into more than one grafPort, it's extremely useful to have each 
procedure save the current grafPort (with GetPort), set its own grafPort, do 
drawing or calculations, and then restore the previous grafPort (with SetPort). 
The pointer to the current grafPort is also available through the global 
pointer thePort, but you may prefer to use GetPort for better readability of 
your program text. For example, a procedure could do a GelPort(savePort) 
before setting its own grafPort and a SelPort(savePon) afterwards to restore 
the previous port 

Procedure GrafDevice (device: Integer); 

GrafDevice sets thePon". device to the given number, which identifies the 
logical output device for this grafPort. QuickDraw uses this information. The 
initial device number is 0, which represents the Lisa screen. 

Procedure SetPortBlts (bin: BltMap); 

SetPortBits sets thePort "^jortBits to any previously defined bitmap. This 
allows you to perform all normal drawing and calculations on a buffer other 
than the Lisa screen—for example, a 640-by-8 output buffer for a dot matrix 
printer, or a small off-screen image for later "stamping" onto the screen. 
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Rennember to prepare all fields of the bitmap before you call SetPortBlts. 

Procedure PortSize (width, height: integer); 

PortSlze changes the size of the current grafPort's portRect Wis does not 
affect the screen; it merely changes the size of the "active area" of the 
grafPort. 

The top left comer of the portRect remains at its same location; the width 
and height of the portRect are set to the given width and height. In other 
words, PortSize moves the bottom right comer of the portRect to a position 
relative to the top left comer. 

PortSize does not change the cllpRgn or the vlsRgn, nor does it affect the 
local coordinate system of the grafPort: it changes only the portRect's width 
and height. Remember that all drawing occurs only in the Intersection of the 
portBitsinunds and the portRect, clipped to the visRgn and the clipRgn. 

Procedure MovePortTo (left61obal,topGlobal: integer); 

MovePortTo changes the position of the current grafPort's portRect This does 
not affect the screen; it merely changes the location at which subsequent 
drawing inside the port will appear. 

The leftGlodal and topGlobal parameters set the distance between the top left 
comer of the portBitsixxnds and the top left comer of the new portRect 
For example, 

hovePortTo(360,182); 

will move the top left comer of the portRect to the center of the screen (if 
portBlts is the Lisa screen) regardless of the local coordinate system. 

Like PortSize, MovePortTo does not change the clipRgn or the vlsRgn, nor 
does it affect the local coordinate system of the grafPort 

Procedure SetOrigin (h,v: integer); 

SetOrigin changes the local coordinate system of the current grafPort This 
does not affect the screen;\\ does, however, affect where subsequent drawing 
and calculation will appear in the grafPort SetOrigin updates the coordinates 
of the portBitsinunds, the portRect, and the vlsRgn. All subsequent drawing 
and calculation routines will use the new coordinate system. 

The h and v parcmeters set the coordinates of the top left comer of the 
portRect All other coordinates are calculated from this point All relative 
distances among any elements in the port will remain the same; only their 
absolute local coordinates will change. 
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NOTE 

SetOrlgin does not update the coordinates of the ollpRgn or the pen; 
these Items stick to the coordinate system (unlike the port's structure^ 
which sticks to the screen). 

SetOrlgin Is useful for adjusting the coordinate system after a scrolling 
operation. (See ScrollRect in Section E.9.13^ Bit Transfer Operations.) 

Procedure SetCllp (rgn: RgnHandle); 

SetClip changes the clipping region of the current grafPort to a region 
equivalent to the given region. Note that this does not change the region 
handle^ but affects the clipping region Itself. Since SetClip makes a copy of 
the given region^ any sudsequent changes you make to that region will not 
affect the clipping region of the port 

You can set the clipping region to any arbitrary region^ to aid you in drawing 
Inside the grafPort. The initial clipRgn is an arbitrarily large rectangle. 

Procedure Getcilp (rgn: RgnHandle); 

Getciip changes the given region to a region equivalent to the clipping region 
of the current grafPort. This is the reverse of what SetClip does. Like 
SetClip, It does not change the region handle. 

Procedure CllpRect (r: Rect); 

CllpRect changes the clipping region of the current grafPort to a rectangle 
equivalent to given rectangle. Note that this does not change the region 
handle, but affects the region Itself. 

Procedure BackPat (pat: Pattern); 

BackPat sets the background pattern of the current grafPort to the given 
pattern. The background pattern Is used In ScrollRect and In all QuickDraw 
routines that perform an "erase" operation. 

E.9.2 Cursor-Handling Routines 

Additional Information on cunor handling can be found In Appendix F, 
Hardware Interface. 

Procedure inltcursor; 

inltCursor sets the current cursor to the predefined arrow cursor, an arrow 
pointing north-northwest, and sets the cursor level to 0, making the cursor 
visible. The cursor level, which Is Initialized to when the system is booted, 
keeps track of the number of times the cursor has been hidden to compensate 
for nested calls to HideCursor and ShowCursor (below). 
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Before you call InltCursor, the cursor Is undefined (or. If set by a previous 
process. It's whatever that process set it to). 

Procedure SetOursor (crsr: Cursor ); 

SetCursor sets the current cursor to the 16-by-16-blt Image In crsr. If the 
cursor Is hidden. It remains hidden and will attain the new appearance when 
It's uncovered; if the cursor Is already visible, it changes to the new 
appearance immediately. 

The cursor image is initialized by InitCursor to a north-northwest arrow, 
visible on the screen. There is no way to retrieve the cunent cursor image. 

Procedure HldeCursor; 

HideCursor removes the cursor from the screen, restoring the bits under it, 
and decrements the cursor level (which inltcursor initialized to 0). Every call 
to HideCursor should be balanced by a subsequent call to ShowCursor. 

Procedure ShovCursor; 

ShowCursor increments the cursor level, which may have been decremented by 
HideCursor, and displays the cursor on the screen if the level becomes 0. A 
call to ShowCursor should balance each previous call to HideCursor. The 
level is not incremented beyond 0, so extra calls to ShowCursor don't hurt. 

If the cursor has been changed (with SetCursor) while hidden, ShowCursor 
presents the new cursor. 

The cursor is initialized by InltCunor to a north-northwest arrow, not hidden. 

Procedure Obscurecursor; 

ObscureCursor hides the cursor until the next time the mouse Is moved, unlike 
HideCursor, it has no effect on the cursor level and must not be balanced by 
a call to ShowCursor. 

E.9.3 Pen and Une-Drawing Routines 

The pen and line-drawing routines all depend on the coordinate system of the 
current grafPort, Remember that each grafPort has its own pen; if you draw 
In one grafPort, change to another, and return to the first, the pen will have 
remained in the same location. 

Procedure HidePen; 

HidePen decrements the current grafPort's pnVls field, which is initialized to 
Xi)i OpenPort; whenever pnVls is negative, the pen does not draw on the 
screen. PnVls keeps track of the number of times the pen has been hidden to 
compensate for nested calls to HidePen and ShowPen (below). HidePen Is 
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called by openRgn, QpenPlcture, and OpenPoly so that you can define regions, 
pictures, and polygons without drawing on the screen. 

Procedure ShonPen; 

ShowPen Increments the current grafPort's pnVls field, which may have been 
decremented by HldePen; if pnVls becomes 0, QuickDraw resumes drawing on 
the screen. Extra calls to ShowPen will Increment pnVls beyond 0, so every 
call to ShowPen should be balanced by a subsequent call to HldePen. 
ShowPen is called by CloseRgn, closePicture, and ClosePoly. 

Procedure GetPen (var pt: Point); 

GetPen returns the current pen location, in the local coordinates of the 
current grafPort 

Procedure GetPenState (var pnState: PenState); 

GetPenstate saves the pen location, size, pattern, and mode in a storage 
variable, to be restored later with SetPenState (below). This is useful when 
calling short subroutines that operate in the current port but must change the 
graphics pen: each such procedure can save the pen's state when it's called, do 
whatever it needs to do, and restore the previous pen state immediately 
before returning. 

The PenState data type is not useful for anything except saving the pen's 
state. 

Procedure SetPenState (pnState: PenState); 

SetPenState sets the pen location, size, pattern, and mode in the current 
grafPort to the values stored in pnState. This is usually called at the end of 
a procedure that has altered the pen parameters and wants to restore them to 
their state at the beginning of the procedure. (See GetPenState, above.) 

Procedure PenSize (width, height: Integer); 

PenSlze sets the dimensions of the graphics pen in the current grafPort. All 
subsequent calls to Line, LineTo, and the procedures that draw framed shapes 
in the current grafPort will use the new pen dimensions. 

The pen dimensions can be accessed in the variable thePort"4)nSl2e, which is 
of type Point If either of the pen dimensions is set to a negative value, the 
pen assumes the dimensions (0,0) and no drawing Is performed. For a 
discussion of how the pen draws, see Section E.7, General Discussion of 
Drawing. 
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Procedure Penhode (mode: Integer); 

PenMode sets the transfer mode through which the pnPat is transferred onto 
the bitmap when lines or shapes are drawa The mode may be any one of the 
pattern transfer modes: 

patoopy patxor notPatOopy notPatxor 

pator patBlc notPatOr notPatBlc 

If the mode is one of the source transfer modes (or negative)^ no drawing is 
performed. The current pen mode can be obtained in the variable 
thePort"4)nMode. The initial pen mode is patCopy, in which the pen pattern 
is copied directly to the bitmap. 

Procedure PenPat (pat: Pattern); 

PenPat sets the pattern that is used by the pen in the current grafPort. The 
standard patterns white, blacky gray, ItGray, and dkGray are predefined; the 
initial pen pattern Is black. The current pen pattern can be obtained in the 
variable thePort"4xiPat, and this value can be assigned (but not compared!) to 
any other variable of type Pattern. 

Procedure PenNormal; 

PenNormal resets the initial state of the pen in the current grafPort, as 
follows: 

Field Setting 

pnsize (1,1) 

pnhode patoopy 

pnPat black 

The pen location is not changed. 

Procedure rioveTo (h,v: Integer); 

MoveTo moves the pen to location (^\,v) in the local coordinates of the current 
grafPort. No drawing is performed. 

Procedure hove (dh,dv: Integer); 

Move moves the pen a distance of dh horizontally and dv vertically from its 
current location; it calls MoveTo(h+dh,v+dv), where (h,v) is the current location. 
The positive directions are to the right and down. No drawing is performed. 
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Procedure LlneTo (rvv: integer); 

LlneTo draws a line from the current pen location to the location specified (In 
local coordinates) by h and v. The new pen location is (h,v) after the line Is 
drawn. See Section E.7^ General Discussion of Drawing. 

If a region or polygon is open and being formed^ its outline is infinitely thin 
and is not affected by the pnsize, pnMode^ or pnPat (See OpenRgn and 
OpenPoly.) 

Procedure Line (drvdv: Integer); 

Line draws a line to the location that is a distance of dh horizontally and dv 
vertically from the current pen location; It calls LlneTo(h-Ktvv+dv), where (Tvv) 
is the current location. The positive directions are to the right and down. 
The pen location becomes the coordinates of the end of the line after the line 
is drawn. See Section E.7^ General Discussion of Drawing. 

If a region or polygon Is open and being formed^ its outline Is Infinitely thin 
and Is not affected by the pnsize, pnMode^ or pnPat (See OpenRgn and 
OpenPoly.) 

E.9.4 Text-Drawing Routines 

Each grafPort has Its own text characteristics, and all these procedures deal 
with those of the current port. 

Procedure TextFont (font: Integer); 

TextFont sets the current grafPort's font (thePort".txFont) to the given font 
number. The initial font number Is 0, which represents the system font. For 
other font numbers, refer to the QDSupport unit, listed In Section E.15. 

Procedure TextFace (face: Style); 

TextFace sets the current grafPort's character style (thePort".t)d^ace). The 
Style data type allows you to specify a set of one or more of the following 
predefined constants: bold, italic, underline, outline, shadow, condense, and 
extend. For example: 

TextFace([bold]); {bold) 

TextFace( [bold, Italic]); (bold and Italic) 

TextFace(tnePort*.t)face*[boldl); (nhatever It was plus bold} 

TextFace(tnePort^.t>f^ace-[bold]); {nhatever it was but not bold) 

TextFace( [ ] ); {normal > 
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Procedure Texuiode (mode: integer); 

TextMode sets the current grafPort's transfer mode for drawing text 
(thePort'.txMode). The mode should be srcOr^ srcXor> or sicBic. The initial 
transfer mode for drawing text is sroor. 

Procedure TextSlze (size: integer); 

TextSlze sets the current grafPort's type size (thePort'.txSize) to the given 
number of points. Any size may be specified, but the result will look best if 
QuickDraw has the font in that size (otherwise it will scale a size it does 
have). The next best result will occur if the given size is an even multiple of 
a size available for the font. If is specified, QuickDraw will choose one of 
the available sizes—whichever is closest to the system font size. The initial 
txSize setting is 0. 

Procedure SpaceExtra (extra: Integer); 

SpaceExtra sets the cunent grafPort's spExtra field, which specifies the 
number of pixels by which to widen each space in a line of text. This is 
useful when text is being fully justified (that is, aligned with both a left and a 
right margin). Consider, for example, a line that contains three spaces; If 
there would normally be six pixels between the end of the line and the right 
margin, you would call SpaceExtra(2) to print the line with full justification. 
The initial spExtra setting is D. 

NOTE 

SpaceExtra will also take a negative argument, but be careful not to 
narrow spaces so much that the text is unreadable. 



Procedure DravChar (ch: cnar); 

DrawChar places the given character to the right of the pen location, with 
the left end of its base line at the pen's location, and advances the pen 
accordingly. If the character Is not in the font, the font's missing symbol is 
drawn. 

Procedure Drawstring (s: Str255); 

Drawstring performs consecutive calls to DrawChar for each character in the 
supplied string; the string is placed beginning at the current pen location and 
extending right No formatting (carriage returns, line feeds, etc.) is performed 
by QuickDraw. The pen location ends up to the right of the last character in 
the string. 
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Procedure DravText (textBuf: QOPtr; flrstByte.byteCount: Integer); 

DrawText draws text from an arbitrary structure In memory specified by 
textBuf, starting flrjtByte bytes Into tne structure and continuing for 
byteCount bytes. The string of text Is placed beginning at the current pen 
location and extending right. No formatting (carriage returns, line feeds, etc.) 
is performed by QuickDraw. The pen location ends up to the right of the last 
character In the string. 

Function CharVldth (ch: char) : integer; 

CharWldth returns the value that will be added to the pen horizontal 
coordinate if the specified character is drawn. CharWldth Includes the effects 
of the stylistic variations set with TextFace; if you change these after 
determining the character width but before actually drawing the character, 
the predetermined width may not be correct. If the character is a space, 
CharWldth also Includes the effect of SpaceExtra. 

Function stringildtn (s: str255) : Integer; 

Strlngwldth returns the width of the given text string, which It calculates by 
adding the widths of all the characters in the string (see CharWldth, above). 
This value will be added to the pen horizontal coordinate if the specified 
string Is drawn. 

Function Textiidth (textBuf: QOPtr; firstByte, byteCount: integer) : 
Integer; 

TextWldth returns the width of the text stored in the arbitrary structure in 
memory specified by textBuf, starting firstByte bytes into the structure and 
continuing for byteCount bytes. It calculates the width by adding the widths 
of all the characters in the text. (See CharWldth, above.) 

Procedure GetFontlnfo (var info: Fontlnfo); 

GetFontlnfo returns the following Information about the current grafPorfs 
character font, taking into consideration the style and size in which the 
characters will be drawn: the ascent, descent, maximum character width (the 
greatest distance the pen will move when a character is drawn), and leading 
(the vertical distance between the descent line and the ascent line below It), 
all in pixels. The Fontlnfo data structure is defined as: 

type Fontlnfo = record 

ascent: Integer; 
descent: integer; 
vidhax: Integer; 
leading: integer 
end; 
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E.93 Drawing In color 

These routines will enable applications to do color drawing in the future when 
Apple supports color output devices for the Lisa. All nonwhlte colors will 
appear as black on black-and-white output devices. 

Procedure ForeColor (color: longlnt); 

ForeColor sets the foreground color for all drawing in the current grafPort 
(thePon".fgColor) to the given color. The following standard colors are 
predefined: blackColor^ whiteColor, redColor, greenColoL blueColor^ cyanColoiy 
magentaColor^ and yellowColor. The initial foreground color is blackCoior. 

Procedure BackColor (color: longlnt); 

BackColor sets the background color for all drawing in the current grafPort 
(lhePorl''i)kColor) to the given color. Eight standard colors are predefined 
(see ForeColor, above). The initial background color is whltecolor. 

Procedure colorBit (KhichBit: integer); 

ColorBlt is called by printing software for a color printer, or other color- 
imaging software, to set the current grafPort's colrBlt field to whichBlt; this 
tells QuickDraw which plane of the color picture to draw into. QuickDraw 
will draw into the plane corresponding to bit number whichBlt Since 
QuickDraw can support output devices that have up to 32 bits of color 
Information per pixel, the possible range of values for whichBlt is through 
31. The Initial value of the colrBit field is 0. 

E.9.6 Calculations with Rectangles 

Calculation routines are independent of the cunent coordinate system; a 
calculation will operate the same regardless of which grafPort is active. 

NOTE 

Remember that if the parameters to one of the calculation routines 
were defined in different grafPorts, you must first adjust them to be in 
the same coordinate system. If you do not adjust them, the result 
returned by the routine may be different from what you see on the 
screen. To adjust to a common coordinate system, see LocalToGlobal 
and GlobalToLocal in Section E.9.17, calculations with Points. 

Procedure SetRect (var r: Rect; left, top, rights bottom: integer); 

SetRect assigns the four boundary coordinates to the rectangle. The result is 
a rectangle with coordinates (left,top,rightj3ottom). 

This procedure is supplied as a utility to help you shorten your program text 
If you want a more readable text at the expense of length, you can assign 
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Integers (or points) directly Into the rectangle's fields, mere Is no significant 
code size or execution speed advantage to either method; one's just easier to 
write, and the other's easier to read. 

Procedure OffsetRect (var r: Rect; dh^dv: integer); 

OffsetRect moves the rectangle by adding dh to each horizontal coordinate 
and dv to each vertical coordinate. If dh and dv are positive, the movement 
is to the right and down; if either is negative, the corresponding movement is 
in the opposite direction. The rectangle retains its shape and size; it's merely 
moved on the coordinate plane. This does not affect the screen unless you 
subsequently call a routine to draw within the rectangle. 

Procedure InsetRect (var r: Rect; dh^dv: Integer); 

InsetRect shrinks or expands the rectangle. The left and right sides are 
moved In by the amount specified by dh; the top and bottom are moved 
toward the center by the amount specified by dv. If dh or dv is negative, the 
appropriate pair of sides Is moved outward Instead of Inward. The effect Is to 
alter the size by 2*dh horizontally and 2*dv vertically, with the rectangle 
remaining centered in the same place on the coordinate plane. 

If the resulting width or height becomes less than 1, the rectangle is set to 
the empty rectangle (0,0^,0^ 

Function SectRect (srcRectA,srdtectB: Rect; var dstRect: Rect) : 
boolean; 

SectRect calculates the rectangle that is the Intersection of the two Input 
rectangles, and returns true if they indeed intersect or false if they do not. 
Rectangles that "touch" at a line or a point are not considered intersecting, 
because their intersection rectangle (really, in this case, an intersection line 
or point) does not enclose any bits on the bitmap. 

If the rectangles do not intersect, the destination rectangle Is set to (0,0,0,0). 
SectRect works correctly even if one of the source rectangles is also the 
destination. 

Procedure UnionRect (srcRectA,srcRectB: Rect; var dstRect: Rect); 

UnlonRect calculates the smallest rectangle which encloses both input 
rectangles. It works conectly even If one of the source rectangles Is also the 
destination. 
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Function PtinRect (pt: Point; r: Rect) : boolean; 

PllnRect determines whether the pixel below and to the right of the given 
coordinate point is enclosed in the specified rectangle^ and returns true if so 
or false if not. 

Procedure Pt2Rect (ptA^ptB: Point; var dstRect: Rect); 

Pt2Rect returns the smallest rectangle which encloses the two input points. 

Procedure PtToAngle (r: Rect; pt: Point; var angle: Integer); 

PtToAngle calculates an integer angle between a line from the center of the 
rectangle to the given point and a line from the center of the rectangle 
pointing straight up (12 o'clock high). The angle Is In degrees from to 359, 
measured clockwise from 12 o'clock, with 90° at 3 o'clock, 180° at 6 o'clock, 
and 270° at 9 o'clock. Other angles are measured relative to the rectangle: If 
the line to the given point goes through the top right corner of the rectangle, 
the angle returned Is 45 degrees, even If the rectangle Is not square; If It goes 
through the bottom right corner, the angle Is 135 degrees, and so on (see 
Figure E-18X 



angle = 45 



angle = 45 




Figure E-18 
PtToAngle 

The angle returned might be used as input to one of the procedures that 
manipulate arcs and wedges, as described in section E.9.10, Graphic operations 
on Arcs and Wedges. 

Function EqualRect (rectA,rectB: Rect) : boolean; 

EqualRect compares the two rectangles and returns true If they are equal or 
false If not. The two rectangles must have Identical boundary coordinates to 
be considered equal. 
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Function EraptyRect (r: Rect) : boolean; 

EmptyRect returns tine if the given rectangle Is an empty rectangle or false 
if not. A rectangle is considered empty if the bottom coordinate is equal to 
or less than the top or the right coordinate is equal to or less than the left. 

E.9.7 Graphic Operations on Rectangles 

These procedures perform graphic operations on rectangles. See also 
ScrollRect in Section E.9.13^ Bit Transfer Operations. 

Procedure FrameRect (r: Rect); 

FrameRect draws an outline just Inside the specified rectangle^ using the 
current grafPorfs pen pattern^ mode^ and size. The outline Is as wide as the 
pen width and as tall as the pen height. It is drawn with the pnPat^ according 
to the pattern transfer mode specified by pnMode. The pen location is not 
changed by this procedure. 

If a region is open and being formed^ the outside outline of the new rectangle 
is mathematically added to the region's boundary. 

Procedure PalntRect (r: Rect); 

PalntRect paints the specified rectangle with the current grafPort's pen 
pattern and mode. The rectangle on the bitmap is filled with the pnPat^ 
according to the pattern transfer mode specified by pnMode. The pen location 
is not changed by this procedure. 

Procedure EraseRect (r: Rect); 

EraseRect paints the specified rectangle with the current grafPort's back- 
ground pattern bkPat (in patCopy mode). The grafPort's pnPat and pnMode are 
ignored; the pen location is not changed. 

Procedure InvertRect (r: Rect); 

InvertRect inverts the pixels enclosed by the specified rectangle: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPaty pnMode, and bkPat are all ignored; the pen location is not changed. 

Procedure FillRect (r: Rect; pat: Pattern); 

FillRect fills the specified rectangle with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is 
not changed. 
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E.9.8 Giapmc operations on Ovals 

Ovals are drawn Inside rectangles that you specify. If the rectangle you 
specify Is square, QuickDraw draws a circle. 

Procedure FrameOval (r: Rect); 

FrameOval draws an outline just Inside the oval that fits Inside the specified 
rectangle, using the current grafPorfs pen pattern, mode, and size. The 
outline Is as wide as the pen width and as tall as the pen height. It is drawn 
with the pnPat, according to the pattern transfer mode specified by pnMode. 
The pen location is not changed by this procedure. 

If a region is open and being formed, the outside outline of the new oval is 
mathematically added to the region's boundary. 

Procedure PaintOval (r: Rect); 

PaintOval paints an oval just inside the specified rectangle with the current 
grafPorfs pen pattern and mode. The oval on the bitmap is filled with the 
pnPat, according to the pattern transfer mode specified by pnMode. The pen 
location is not changed by this procedure. 

Procedure EraseOval (r: Rect); 

EraseOval paints an oval just inside the specified rectangle with the current 
grafPbrt's background pattern bkPat (in patCopy mode). The grafPorfs pnPat 
and pnMode are ignored; the pen location is not changed. 

Procedure InvertOval (r: Rect); 

InvertOval Inverts the pixels enclosed Xi'i an oval just inside the specified 
rectangle: every white pixel becomes black and every black pixel becomes 
white. The grafPorfs pnPat, pnMode, and bkPat are all Ignored; the pen 
location is not changed. 

Procedure FillOval (r: Rect; pat: Pattern); 

FillOval fills an oval just inside the specified rectangle with the given pattern 
(In patCopy mode). The grafPorfs pnPat, pnMode, and bkPat are all ignored; 
the pen location is not changed. 

E.9.9 Graphic operations on Rounded-Comer Rectangles 

Procedure FrameRoundRect (r: Rect; ovaliidth^ovalHeight: integer); 

FranneRoundRect draws an outline just Inside the specified rounded-corner 
rectangle, using the current grafPorfs pen pattern, mode, and size. CValWidth 
and oyalHeight specify the diameters of curvature for the comers (see Figure 
E-19). The outline is as wide as the pen width and as tall as the pen height. 
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It is drawn with the pnPat, according to the pattern transfer mode specified 
by pnMode. The pen location is not changed by this procedure. 



ovalWidth 
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Figure E-19 
Rounded-Comer Rectangle 

If a region is open and being formed, the outside outline of the new rounded- 
corner rectangle is mathematically added to the region's boundary. 

Procedure PalntRoundRect (r: Rect; ovai»ldtn,ovalHelgnt: Integer); 

PaintRoundRect paints the specified rounded-corner rectangle with the 
current grafPort's pen pattern and mode. O/alWldth and ovalHeight specify 
the diameters of curvature for the corners. The rounded-corner rectangle on 
the bitmap is filled with the pnPat, according to the pattern transfer mode 
specified by pnMode. The pen location is not changed by this procedure. 

Procedure EraseRoundRect (r: Rect; oval»ldth, ovalHeight: integer); 

EraseRoundRect paints the specified rounded-corner rectangle with the 
current grafPorfs background pattern bkPat (in patCopy mode). O/alWidth and 
ovalHeight specify the diameters of curvature for the corners. The grafPort's 
pnPat and pnMode are ignored; the pen location is not changed. 

Procedure InvertRoundRect (r: Rect; ovalWldth, ovalHeight: integer); 

invertRoundRect Inverts the pixels enclosed by the specified rounded-corner 
rectangle: every white pixel becomes black and every black pixel becomes 
white. OvalWidth and ovalHelc^t specify the diameters of curvature for the 
corners. The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen 
location is not changed. 
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Procedure FlllRoundRect (r: Rect; ovalildth^ovalHel^t: Integer; pat: 

Pattern); 

FlllRoundRect fills the specified rounded-corner rectangle with the given 
pattern (in patCopy mode). O/alWldth and ovalHelg^t specify the diameters of 
curvature for the comers. The grafPort's pnPat, pnMode, and DkPat are all 
Ignored; the pen location is not changed. 

E.9.10 Graphic Operations on Arcs and Wedges 

These procedures perform graphic operations on arcs and wedge-shaped 
sections of ovals. See also PtToAngle in section E.9.6^ Calculations with 
Rectangles. 

Procedure FrameArc (r: Rect; startAngle^arcAngle: Integer); 

FrameArc draws an arc of the oval that fits inside the specified rectangle, 
using the current grafPort's pen pattern, mode, and size. StartAngle indicates 
Where the arc begins and is treated mod 360. ArcAngle defines the extent of 
the arc. The angles are given in positive or negative degrees; a positive angle 
goes clockwise, while a negative angle goes counterclockwise. Zero degrees is 
at 12 o'clock high, 90" (or -270") is at 3 o'clock, 180" (or -180") is at 6 
o'clock, and 270" (or -90") is at 9 o'clock, other angles are measured relative 
to the enclosing rectangle: a line from the center of the rectangle through its 
top right corner is at 45 degrees, even if the rectangle is not square; a line 
through the bottom right comer is at 135 degrees, and so on (see Figure E-20). 
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Figure E-20 
Operations on Arcs and Wedges 
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Tne arc is as wide as the pen width and as tall as the pen height, it is drawn 
with the pnPat, according to the pattern transfer mode specified by pnMode. 
The pen location is not changed Dy this procedure. 

W/NRNING 

FrameArc differs from other GJuickDraw procedures that frame shapes 
in that the arc is not mathematically added to the boundary of a 
region that is open and being formed. 



Procedure PaintArc (r: Rect; startAngle^arcAngle: Integer); 

PaintArc paints a wedge of the oval just inside the specified rectangle with 
the current grafPorfs pen pattern and mode. StartAngle and ancAngle define 
the arc of the wedge as in FrameArc. The wedge on the bitmap is filled with 
the pnPat according to the pattern transfer mode specified by pnModa The 
pen location is not changed by this procedure. 

Procedure EraseArc (r: Rect; startAngle^arcAngle: integer); 

EraseArc paints a wedge of the oval Just inside the specified rectangle with 
the current grafPort's background pattern bkPat (in patcopy mode). 
StartAngle and ancAngle define the arc of the wedge as in FrameArc. The 
grafPort's pnPat and pnMode are Ignored; the pen location is not changed. 

Procedure InvertArc (r: Rect; startAngle^arcAngle: Integer); 

InvertArc inverts the pixels enclosed by a wedge of the oval just inside the 
specified rectangle: every white pixel becomes black and every black pixel 
becomes white. StartAngle and arcAngle define the arc of the wedge as in 
FrameArc. The grafPort's pnPat, pnMode, and bkPat are all Ignored; the pen 
location Is not changed. 

Procedure FillArc (r: Rect; StartAngle, arcAngle: integer; pat: 
Pattern); 

FillArc fills a wedge of the oval just inside the specified rectangle with the 
given pattern (In patcopy mode). StartAngle and arcAngle define the arc of 
the wedge as in FrameArc. The grafPort's pnPat, pnMode, and bkPat are all 
ignored; the pen location is not changed. 
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E.9.11 Calculations wltn Regions 

NOTE 

RememDer that if the parameters to one of the calculation routines 
were defined In different grafPorts, you must first adjust them to be in 
the same coordinate system. If you do not adjust them, the result 
returned by the routine may be different from what you see on the 
screen. To adjust to a common coordinate system, see LocalToGlobal 
and GlobalToLocal In Section E.9.17, calculations wltn Points. 



Function NewRgn : RgnHandle; 

NewRgn allocates space for a new, dynamic, variable-size region, initializes it 
to the empty region (0,0A0)^ and returns a handle to the new region. Only 
this function creates new regions; all other procedures just alter the size and 
shape of regions you create. OpenPort calls NewRgn to allocate space for the 
port's vlsRgn and clipRgn. 

Except when using visRgn or clipRgn, you must call NewRgn before 
specifying a region's handle In any drawing or calculation procedure. 

Ntever refer to a region without using its handle. 



Procedure DisposeRgn (rgn: RgnHandle); 

DisposeRgn deallocates space for the region whose handle Is supplied, and 
returns the memory used by the region to the free memory pool, use this 
only after you are completely through with a temporary region. 

WARNING 

Never use a region once you have deallocated it, or you will risk being 
hung Xi'^ dangling pointers! 



Procedure CopyRgn (srcRgn,dstRgn: RgnHandle); 

CopyRgn copies the mathematical structure of srcRgn into dstRgn; that is, it 
makes a duplicate copy of srcRgn. Once this is done, srcRgn may be altered 
(or even disposed of) without affecting dstRgn. CcpyRgn does not create the 
cfestlnatlon region: you must use NewRgn to create the dstRgn before you 
call CopyRgn. 
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Picxjedure SetEnptyRgn (rgn: RgnHandle); 

SetEmptyRgn destroys the previous structure of the given region, then sets the 
new structure to the empty region (O^^^X 

Procedure SetRectRgn (rgn: RgnHandle; left, top, ric^t, bottom: integer); 

SetRectRgn destroys the previous structure of the given region, then sets the 
new structure to the rectangle specified by left, top, right, and bottom. 

If the specified rectangle is empty (i.e., left>-right or top>-bottom), the region 
is set to the empty region (0,0,0^3). 

Procedure RectRgn (rgn: RgnHandle; r: Rect); 

RectRgn destroys the previous structure of the given region, then sets the new 
structure to the rectangle specified by r. This is operationally synonymous 
with SetRectRgn, except the input rectangle Is defined by a rectangle rather 
than by four boundary coordinates. 

Procedure openRgn; 

OpenRgn tells QuickDraw to allocate temporary space and start saving lines 
and framed shapes for later processing as a region definition. While a region 
is open, all calls to Line, LineTo, and the procedures that draw framed shapes 
(except arcs) affect the outline of the region. Only the line endpoints and 
shape boundaries affect the region definition; the pen mode, pattern, and size 
do not affect it. In fact, OpenRgn calls HldePen, so no drawing occurs on the 
screen while the region is open (unless you called ShowPen just after OpenRgn, 
or you called ShowPen previously without balancing it by a call to HIdePen). 
Since the pen hangs below and to the right of the pen location, drawing lines 
with even the smallest pen will change bits that lie outside the region you 
define. 

The outline of a region is mathematically defined and infinitely thin, and 
separates the bitmap into two groups of bits: those within the region and 
those outside It. A region should consist of one or more closed loops. Each 
framed shape itself constitutes a loop. Any lines drawn with Line or LineTo 
should connect with each other or with a framed shape. Even though the 
on-screen presentation of a region Is clipped, the definition of a region is not; 
you can define a region anywhere on the coordinate plane with complete 
disregard for the location of various grafPort entitles on that plane. 

When a region Is open, the current grafPort's rgnSave field contains a handle 
to Information related to the region definition. If you want to temporarily 
disable the collection of lines and shapes, you can save the current value of 
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this field, set tne field to niL and later restore the saved value to resume the 
region definition. 

WARNING 

Do not call OpenRgn while another region is already open. All open 
regions but the most recent will behave strangely. 



Procedure CloseRgn (dstRgn: RgnHandle); 

CloseRgn stops the collection of lines and framed shapes, organizes them into 
a region definition, and saves the resulting region into the region Indicated by 
dstRgn. You should perform one and only one CloseRgn for every OpenRgn. 
CloseRgn calls ShowPen, balancing the HidePen call made by cpenRgn. 

Here's an example of how to create and open a region, define a barbell shape, 
close the region, and draw it: 

barbell := NewRgn; {make a new region} 

OpenRgn; {begin collecting stuff} 

SetRect(tempRect,20,20,30,50); {form the left weight} 

FrameOval ( teupRect ); 

SetRect(tempRect,30,30,80,40); {form the bar} 

FrameRect ( tempRect ); 

setRect(tempRect,80,20,90,50); {form the rl^t weight} 

Fr ameOval ( t empRect ); 
closeRgn(barbell); {i»e're done; save in barbell} 

FillRgn(barbell, black); {draw it on the screen} 

DisposeRgn(barbeli); {we don't need you anymore..} 

Procedure OffsetRgn (rgn: RgnHandle; dh,dv: integer); 

OffsetRgn moves the region on the coordinate plane, a distance of dh 
horizontally and dv vertically. This does not affect the screen unless you 
subsequently call a routine to draw the region. If dh and dv are positive, the 
movement is to the right and down; if either Is negative, the corresponding 
movement Is in the opposite direction. The region retains Its size and shape. 

NOTE 

OffsetRgn is an especially efficient operation, because most of the data 
defining a region is stored relative to ignBBox and so isn't actually 
changed by OffsetRgn. 
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Procedure insetRgn (rgn: RgnHandle; dh,clv: Integer); 

insetRgn shrinks or expands the region. All points on the region boundary are 
moved inwards a distance of dv vertically and dh horizontally; if dh or dv is 
negative, the points are moved outwards in that direction. InsetRgn leaves 
the region "centered" at the same position, but moves the outline in (for 
positive values of dh and dv) or out (for negative values of dh and dv). 
InsetRgn of a rectangular region works just like InsetRect. 

Procedure SectRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

SectRgn calculates the intersection of two regions and places the intersection 
in a third region, mis Oues mt cieate t/^ ctesUnatim legJm: you must use 
NewRgn to create dstRgn before you call SectRgn. The dslRgn can be one of 
the source regions, if desired. 

If the regions do not intersect, or one of the regions is empty, the destination 
is set to the empty region (0,0,0,0). 

Procedure UnlortRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

unlonRgn calculates the union of two regions and places the union in a third 
region. This does not create the destination region- you must use NewRgn to 
create dstRgn before you call UnlonRgn. The dstRgn can be one of the 
source regions, if desired. 

If both regions are empty, the destination is set to the empty region (0,0,0,0). 

Procedure DlffRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

DiffRgn subtracts srcRgnB from srcRgnA and places the difference in a third 
region, mis does not create the destination region: you must use NewRgn to 
create dstRgn before you call DiffRgn. The dstRgn can be one of the source 
regions, if desired. 

If the first source region is empty, the destination is set to the empty region 

(o,ao,ox 

ProcKlure XorRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

xorRgn calculates the difference between the union and the intersection of 
two regions and places the result in a third region, mis does not create the 
destlnatim region: you must use NewRgn to create dstRgn before you call 
XorRgn. The dstRgn can be one of the source regions, if desired. 

If the regions are coincident, the destination is set to the empty region 
(0,0,0,0). 
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Function PtinRgn (pt: Point; rgn: RgnHandle) : txwlean; 

PtInRgn checks whether the pixel below and to the right of the given 
coordinate point is within the specified region^ and returns true if so or false 
if not 

Function RectlnRgn (r: Rect; rgn: RgnHandle) : Doolean; 

RectlnRgn checks whether the given rectangle intersects the specified region^ 
and returns true if the intersection encloses at least one bit or false if not. 

Function EqualRgn (rgnft,rgnB: rgnHandle) : boolean; 

EqualRgn compares the two regions and returns true if they are equal or false 
if not. The two regions must have identical sizes, shapes, and locations to be 
considered equal. Any two empty regions are always equal. 

Function EnptyRgn (rgn: RgnHandle) : boolean; 

EmptyRgn returns true if the region is an empty region or false if not. Some 
of the circumstances in which an empty region can be created are: a NewRgn 
call; a CopyRgn of an empty region; a SetRectRgn or RectRgn with an empty 
rectangle as an argument; CloseRgn without a previous OpenRgn or with no 
drawing after an OpenRgn; OffsetRgn of an empty region; InsetRgn with an 
empty region or too large an inset; SectRgn of nonintersecting regions; 
UnionRgn of two empty regions; and DiffRgn or XorRgn of two identical or 
nonintersecting regions. 

E.9.12 Graphic Operations on F^ons 

These routines all depend on the coordinate system of the current grafPort. If 
a region is drawn in a different grafPort than the one in which it was defined. 
It may not appear in the proper position Inside the port. 

Procedure FrameRgn (rgn: RgnHandle); 

FrameRgn draws a hollow outline just Inside the specified region, using the 
current grafPorfs pen pattern, mode, and size. The outline is as wide as the 
pen width and as tall as the pen height; under no circumstances will the 
frame go outside the region boundary. The pen location is not changed by 
this procedure. 

If a region Is open and being formed, the outside outline of the region being 
framed Is mathematically added to that region's boundary. 

Procedure PalntRgn (rgn: RgnHandle); 

PaintRgn paints the specified region with the current grafPorfs pen pattern 
and pen mode. The region on the bitmap is filled with the pnPat, according 
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10 the pattern transfer mode specified by pnMode. The pen location is not 
changed by this procedure. 

Procedure EraseRgn (rgn: RgnHandle); 

EraseRgn paints the specified region with the current grafPort's background 
pattern bkPat (In patcopy mode). The grafPort's pnPat and pnMode are 

ignored; the pen location is not changed. 

Procedure irwertRgn (rgn: RgnHandle); 

InvertRgn inverts the pixels enclosed by the specified region: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat, pnMode, and bkPat are all ignored; the pen location is not changed. 

Procedure FlllRgn (rgn: RgnHandle; pat: Pattern); 

FillRgn fills the specified region with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is 
not changed. 

E.9.13 Bit Transfer Operations 

Procedure ScrollRect (r: Rect; dh,dv: Integer; updateRgn: RgnHandle); 

ScrollRect shifts C'scrolls") those bits inside the intersection of the specified 
rectangle, visRgn, clIpRgn, portRect, and portBlts-Dounds. The bits are shifted 
a distance of dh horizontally and dv vertically. The positive directions are to 
the right and down. No other bits are affected. Bits that are shifted out of 
the scroll area are lost; they are neither placed outside the area nor saved. 
The grafPort's background pattern dkPat fills the space created by the scroll. 
In addition, updateRgn is changed to the area filled with DkPat (see Figure 
E-21). 
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Figure E-21 
Scrolling 



Figure E-21 shows that the pen location after a scroilRect Is In a different 
position relative to what was scrolled in the rectangle. The entire scrolled 
Item has Deen moved to different coordinates. To restore It to Its coordinates 
before the ScroilRect you can use the SetOrlgin procedure. For example, 
suppose the OstRect here Is the portReci of the grafport and Its top left 
corner is at (95A20). Sel0rigln(1054l5) will offset the coordinate system to 
compensate for the scroll. Since the clipRgn and pen location are not offset, 
they move down and to the left. 

Procedure CopyBits (srcBits^dstBlts: BltMap; srcRect,dstRect: Rect; 
mode: Integer; maskRgn: RgnHandle); 

CopyBits transfers a Dlt image between any two Dltmaps and clips the result 
to the area specified by the maskRgn parameter. The transfer may be 
performed in any of the eight source transfer modes. The result Is always 
clipped to the maskRgn and the boundary rectangle of the destination bitmap; 
If the destination bitmap is the current grafPort's poriBlls, It Is also clipped 
to the intersGction of the grafPorfs olipRgn and visRgn. If you do not want 
to clip to a maskRgn, Just pass nil for the maskRgn parameter. 

The dstRect and maskRgn coordinates are in terms of the dstBltsi)ounds 
coordinate system, and the srcRect coordinates are in terms of the 
srcBltsinunds coordinates. 

The bits enclosed by the source rectangle are transferred into the destination 
rectangle according to the rules of the chosen mode. 
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The source transfer modes are as follows: 



srcCopy 
srcOr 



srcXor 
srcBlc 



notSrcCopy 
notSrcOr 



notSrcXor 
notSrcBic 



The source rectangle Is completely aligned with the destination rectangle; If 
the rectangles are of different sizes^ the bit image is expanded or shrunk as 
necessary to fit the destination rectangle. For example^ if the hit Image is a 
circle in a square source rectangle, and the destination rectangle is not 
square, the bit image appears as an oval in the destination (see Figure E-22). 
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Figure E-22 
Gperation of CopyBits 



E.9.14 Pictures 



Function openPlcture (plcFrame: Rect) : PlcHanaie; 

OpenPicture returns a handle to a new picture which has the given rectangle 
as Its picture frame, and tells QuickDraw to start saving as the picture 
definition all calls to drawing routines and all picture comments (if any). 

OpenPicture calls HidePen, so no drawing occurs on the screen while the 
picture is open (unless you call ShowPen just after OpenPicture, or you called 
ShowPen previously without balancing it by a call to HidePen). 

When a picture is open, the current grafPort's picSave field contains a handle 
to information related to the picture definition. If you want to temporarily 
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dlsaDle the collection of routine calls and picture comments, you can save tne 
current value of this field, set the field to nil, and later restore the saved 
value to resume the picture definition. 

WARNING 

Do not call openPicture while another picture is already open. 



Procedure closePlcture; 

ClosePlcture tells QuickDraw to stop saving routine calls and picture 
comments as the definition of the currently open picture. You should perform 
one and only one ClosePlcture for every OpenPicture. ClosePlcture calls 
ShowPen, Dalancing the HidePen call made Oy OpenPicture. 

Procedure PlcConinent (klnd^dataSlze: Integer; dataHandle: QDHandle); 

Piccomment inserts the specified comment into the definition of the currently 
open picture. Kind identifies the type of comment. DataHandle is a handle 
to additional data if desired, and datasize is the size of that data in hytes. If 
there is no additional data for the comment, dataHandle should be nil and 
datasize should be 0. The application that processes the comment must 
Include a procedure to do the processing and store a pointer to the procedure 
in the data structure pointed to by the grafProcs field of the grafPort (see 
Section E.io, Customizing QuickDraw Operations). 

Procedure DraiiPlcture (myPicture: PlcHandle; dstRect: Rect); 

DrawPicture draws the given picture to scale In dstRect, expanding or 
shrinking it as necessary to align the borders of the picture frame with 
dstRect DrawPicture passes any picture comments to the procedure accessed 
indirectly through the grafProcs field of the grafPort (see PicComment above). 

Procedure KillPicture (myPicture: PicHandie); 

KliiPicture deallocates space for the picture whose handle is supplied, and 
returns the memory used by the picture to the free memory pool. Use this 
only when you are completely through with a picture. 

E.9.15 Calculations with Polygons 

Function OpenPoly : PolyHandle; 

OpenPoly returns a handle to a new polygon and tells QuickDraw to start 
saving the polygon definition as specified by calls to line-drawing routines. 
While a polygon is open, all calls to Line and LineTo affect the outline of the 
polygon. Only the line endpoints affect the polygon definition; the pen mode, 
pattern, and size do not affect it. In fact, OpenPoly calls HidePen, so no 
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drawing occurs on the screen while the polygon Is open (unless you call 
ShowPen just after openPoly^ or you called ShowPen previously without 
oalancing it by a call to HldePen). 

A polygon should consist of a sequence of connected lines. Even though the 
on-screen presentation of a polygon is clipped, the definition of a polygon is 
not; you can define a polygon anywhere on the coordinate plane with complete 
disregard for the location of various grafPort entities on that plane. 

When a polygon is open, the current grafPorfs poiySave field contains a 
handle to information related to the polygon definition. If you want to 
temporarily disable the polygon definition, you can save the current value of 
this field, set the field to nil, and later restore the saved value to resume the 
polygon definition. 

WARNING 

Do not call openPoly while another polygon is already open. 



Procedure closePoly; 

ClosePoly tells QuickDraw to stop saving the definition of the currently open 
polygon and computes the polyBBox rectangle. You should perform one and 
only one ClosePoly for every OpenPoly. ClosePoly calls ShowPen, balancing 
the HldePen call made by OpenPoly. 

Here's an example of how to open a polygon, define it as a triangle, close it, 
and draw it: 



trlPoly := OpenPoly; 

MoveTo(300, 100); 

LlneTo(400,200); 

LineTo(20Q,200); 

LineTo(300, lOO); 
ClosePoly; 

FlilPoly(trlPoly, gray); 
KillPoly(trlPoly); 



save handle and begin collecting stuff} 

move to first point and > 

form } 

the } 

triangle } 

stop collecting stuff } 

draw It on the screen } 

we're all done } 



Procedure KillPoly (poly: PolyHandle); 

KillPoly deallocates space for the polygon whose handle is supplied, and 
returns the memory used by the polygon to the free memory pool. Use this 
only after you are completely through with a polygon. 

Procedure OffsetPoly (poly: PolyHandle; dh^dv: integer); 

OffsetPoly moves the specified polygon on the coordinate plane, a distance of 
dh horizontally and dv vertically. This does not affect the screen unless you 
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suDsequently call a routine to draw the polygon, if dh and dv are positive^ 
the movement is to the right and down; if either is negative^ the correspond- 
ing movement is in the opposite direction. The polygon retains its shape and 
size. 

NOTE 

OffsetPoly is an especially efficient operation^ because the data 
defining a polygon is stored relative to polyStart and so isn't actually 
changed by OffsetPoly. 



E.9.16 Graphic Operations on Polygons 

Procedure FraroePoly (poly: PolyHandle); 

FramePoly plays back the line-drawing routine calls that define the given 
polygon, using the current grafPort's pen pattern, mode, and size. The pen 
will hang below and to the right of each point on the boundary of the 
polygon; thus, the polygon drawn will extend beyond the right and bottom 
edges of poly" "^wlyBBox by the pen width and pen height, respectively. All 
other graphic operations occur strictly within the boundary of the polygon, as 
for other shapes. You can see this difference in Figure E-23, where each of 
the polygons is shown with its poiyBBox 





FramePoly 



PaintPoly 



Figure E-23 
Drawing Polygons 



If a polygon is open and being formed, FramePoly affects the outline of the 
polygon |jst as if the line-drawing routines themselves had been called. If a 
region is open and being formed, the outside outline of the polygon being 
framed is mathematically added to the region's boundary. 
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Prtx»dure PalntPoly (poly: PolyHandle); 

PaintPoly paints the specified polygon with the current grafPorfs pen pattern 
and pen mode. The polygon on the bitmap is filled with the pnPat according 
to the pattern transfer mode specified by pnMocte, The pen location is not 
changed by this procedure. 

Procedure ErasePoly (poly: PolyHandle); 

ErasePoly paints the specified polygon with the current grafPort's background 
pattern bkPat (in patCopy modeX The pnPat and pnMode are ignored; the pen 
location is not changed. 

Procedure invertPoly (poly: PolyHandle); 

InvertPoly inverts the pixels enclosed by the specified polygon: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat pnMode, and bkPat are all ignored; the pen location is not changed. 

Procedure FlllPoly (poly: PolyHandle; pat: Pattern); 

FillPoly fills the specified polygon with the given pattern (in patCopy mode). 
The grafPort's pnP^t, pnMode, and bkPat are all ignored; the pen location is 
not changed. 

E.9.17 calculations with Points 

Procedure AddPt (srcPt: Point; var dstPt: Point); 

AddPt adds the coordinates of srcPt to the coordinates of dstPt, and returns 
the result in dstPt 

Procedure SubPt (srcPt: Point; var dstPt: Point); 

SudPt subtracts the coordinates of srcPl from the coordinates of dstPt, and 
returns the result in dstPt 

Procedure SetPt (var pt: Point; h^v: integer); 

SetPt assigns two integer coordinates to a variable of type Point 

Function EqualPt (ptA^ptB: Point) : boolean; 

EqualPt compares the two points and returns true if they are equal or false if 
not. 
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Procedure LocalToGlobal (var pt: Point); 

LocalToGlodal converts the given point from the current grafPort's local 
coordinate system Into a global coordinate system with the origin (0^3) at the 
top left comer of the port's bit Image (such as the screen). This global point 
can then be compared to other global points, or be changed Into the local 
coordinates of another grafPort 

Since a rectangle 4s^ defined by two points, you can convert a rectangle Into 
global coordinates by performing two LocalToGlobal calls. You can also 
convert a rectangle, region, or polygon Into global coordinates by calling 
OffsetRect, OffsetRgn, or OffsetPoly. For examples, see GlobalToLocal below. 

Procedure GlodalToLocal (var pt: Point); 

GlobalToLocal takes a point expressed In global coordinates (with the top left 
corner of the bitmap as coordinate (0,0)) and converts It Into the local 
coordinates of the current grafPort. The global point can be obtained with 
the LocalToGlobal call (see above). For example, suppose a game draws a 
"ball" within a rectangle named ballRect, defined In the grafPort named 
gamePort (as Illustrated below In Figure E-24). If you want to draw that ball 
In the grafPort named selectPort, you can calculate the ball's selectPort 
coordinates like this: 

SetPort(gainePort); { start in origin port 

selectBall := ballRect; { make a copy to be moved \ 

LocalToGlobal(select6all.topLeft); { put both comers Into 

LocalToGlobal(selectBall.botRlght); { global coordinates 

SetPort(selectPort); {switch to destination port} 

GlobalToLocal(selectBall.topLeft); { put both comers Into } 
Glot)alToLocal(selectBall.botRlght);{ these local coordinates } 
FlllOval(selectBall,ballColor); { now you have the ball! } 
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Figure E-24 
Converting between Coordinate Systems 

You can see from Figure E-24 that LocalToGlobal and GloDalToLocal simply 
offset the coordinates of the rectangle by the coordinates of the top left 
corner of the local grafPort's boundary rectangle. You could also do this with 
OffsetRect. In fact^ the way to convert regions and polygons from one 
coordinate system to another is with OffsetRgn or OffsetPoly rather than 
LocalToGlobal and GlobalToLocal. For example, if myRgn were a region 
enclosed by a rectangle having the same coordinates as ballRect in gamePort, 
you could convert the region to global coordinates with 

Off setRgn(myRgn, -20, -40); 
and then convert it to the coordinates of the selectPort grafPort with 

CJffsetRgn(myRgn, 15, -30); 

E.9.18 Miscellaneous utilities 

Function Random : integer; 

Random returns an integer, uniformly distributed pseudo-random, in the range 
from -32768 through 32767. The value returned depends on the global 
variable randSeed, which InitGraf initializes to 1; you can start the sequence 
over again from where It began by resetting rancseed to i. 
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Function GetPlxei (rvv: Integer) : txwlean; 

GetPlxel looks at the pixel associated with the given coordinate point and 
returns true if it is black or false if it is white. The selected pixel is 
immediately below and to the right of the point whose coordinates are given 
in h and v, in the local coordinates of the current grafPort. There is no 
guarantee that the specified pixel actually belongs to the port, however; it 
may have been drawn by a port overlapping the current one. To see if the 
point indeed belongs to the current port, call PtInRgn(pt,thePort".visRgn)i 

Procedure stuff Hex (thingPtr: QOPtr; s: Str255); 

StuffHex pokes bits (expressed as a string of hexadecimal digits) into any data 
structure. This is a good way to create cursors, patterns, or bit images to be 
"stamped" onto the screen with CopyBits. For example, 

stuff Hex(astrlpes, ' 0102040810204080 ' ) 

places a striped pattern into the pattern variable stripes. 
W/>RNING 

There is no range checking on the size of the destination variable. It's 
easy to overrun the variable and destroy something if you don't know 
what you're doing. 



Procedure ScalePt (var pt: Point; srcRect,dstReot: Rect); 

A width and height are passed in pt; the horizontal component of pi is the 
width, and the vertical component of pi is the height. ScalePt scales these 
measurements as follows and returns the result in pt It multiplies the given 
width by the ratio of dslRecl's width to sicRecl's width, and multiplies the 
given height by the ratio of dslRecfs height to srcRect's height. In Figure 
E-25, where dslRecl's width is twice srcRecl's width and its height is three 
times srcRecl's height, the pen width is scaled from 3 to 6 and the pen height 
is scaled from 2 to 6. 
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ScslePt scales pen size (3,2) to (6,6) 
MapPt maps point (3,2) to (18,7) 

Figure E-25 
ScalePt and MapPt 

Procedure MapPt (var pt: Point; srcRect^dstRect: Rect); 

Given a point within srcRect^ MapPt maps it to a similarly located point 
within dstRect (that is, to where it would fall if it were part of a drawing 
being expanded or shrunk to fit dstRect). The result is returned in pt A 
corner point of srcRect would he mapped to the corresponding comer point of 
dstRect and the center of srcRect to the center of dstRect In Figure E-25 
above, the point (3^) in srcRect is mapped to (18,7) in dstRect FromRect and 
dstRect may overlap, and pt need not actually be within srcRect 
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WARNING 

RememDer, If you are going to draw Inside the rectangle In dstRect, 
you will probably also want to scale the pen size accordingly with 
ScaiePt. 

Procedure MapRect (var r: Rect; srcRect^dstRect: Rect); 

Given a rectangle within srcRect MapRect maps it to a similarly located 
rectangle within dstRect by calling MapPt to map the top left and bottom 
right cornen of the rectangle. The result is returned in r. 

Procedure riapRgn (rgn: RgnHandle; srcRect, dstRect: Rect); 

Given a region within srcRect, MapRgn maps it to a similarly located region 
within dstRect by calling MapPt to map all the points in the region. 

Procedure riapPoly (poly: PolyHandle; srcRect^ dstRect: Rect); 

Given a polygon within srcRect MapPoly maps It to a similarly located 
polygon within dstRect by calling MapPt to map all the points that define the 
polygon. 

E.10 Customizing QuickDraw Operations 

For each shape that QuickDraw knows how to draw^ there are procedures that 
perform these basic graphic operations on the shape: frame, paint, erase. 
Invert, and fill. Those procedures in turn call a low-level drawing routine for 
the shape. For example, the FrameOval, PaintOval, EraseOval, InvertOval, and 
FiiiOval procedures all call a low-level routine that draws the oval. For each 
type of object QuickDraw can draw, including text and lines, there is a 
pointer to such a routine. By changing these pointers, you can Install your 
own routines, and either completely override the standard ones or call them 
after your routines have modified parameters as necessary. 

Other low-level routines that you can Install in this way are: 

• The procedure that does bit transfer and is called by CopyBits. 

• The function that measures the width of text and is called by CharWidth, 
Strlngwidth, and Textwidth. 

• The procedure that processes picture comments and is called by 
DrawPicture. The standard such procedure ignores picture comments. 

• The procedure that saves drawing commands as the definition of a picture, 
and the one that retrieves them. This enables the application to draw on 
remote devices, print to the disk, get picture input from the disk, and 
support large pictures. 
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The grafProcs field of a grafPort determines which low-level routines are 
called; if It contains nil, the standard routines are called, so that all 
operations In that grafPort are done in the standard ways descrihed In this 
appendix. You can set the grafProcs field to point to a record of pointers to 
routines. The data type of grafProcs Is GjDProcsPir: 



type QDProcsPtr = *QDProcs, 






QDProcs = record 






textProc: 


QOPtr; 


{text drawing} 


llnePruu: 


QOPtr; 


{line drawing} 


rectProc: 


QOPtr; 


{rectangle drawing} 


rRectProc: 


QOPtr; 


{roundRect drawing} 


ovalProc: 


QOPtr; 


{oval drawing} 


arcProc: 


QOPtr; 


{arc/wedge drawing} 


polyProc: 


QOPtr; 


{polygon drawing} 


rgnProc: 


QOPtr; 


{region drawing} 


bltsProc: 


QOPtr; 


{bit transfer} 


conmentPitK;; 


QOPtr; 


{picture comment 
processing} 


txtteasProc: 


QOPtr; 


{text width measurement} 


getPicProc: 


QOPtr; 


{picture retrieval} 


putPicProc: 


QOPtr 


{picture saving} 



end; 



Procedure setstdProcs (var procs: QDProcs); 

SetStdProcs is provided to assist you in setting up a QDProcs record. It sets 
all the fields of the given QDProcs to point to the standard low-level 
routines. You can then change the ones you wish to point to your own 
routines. For example, if your procedure that processes picture comments is 
named MyComments, you will store fiMyComments in the commentProc field 
of the QDProcs record. 

The routines you install must of course have the same calling sequences as 
the standard routines, which are described below. The standard drawing 
routines tell which graphic operation to perform from a parameter of type 
GrafVerb. 

type GrafVerb = (frame, painty erase, invert, fill); 

When the grafVerb Is fill, the pattern to use when filling is passed In the 
fillPat field of the grafPort. 

Procedure StdText (byteCount: integer; textBuf: QOPtr; numer,denom: 
Point); 

StdText is the standard low-level routine for drawing text, it draws text from 
the arbitrary structure in memory specified by textBuf, starting from the first 
byte and continuing for byteCount bytes. Numer and denom specify the 
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scaling. If any: numer.v over denom.v gives the vertical scaling^ and numer.h 
over denonUi gives the horizontal scaling. 

Procedure stxLine (newPt: Point); 

StdLine is the standard low-level routine for drawing a line. It draws a line 
from the current pen location to the location specified (In local coordinates) 
by newPt 

Procedure StdRect (verb: Graf Verb; r: Rect); 

StdRect is the standard low-level routine for drawing a rectangle. It draws 
the given rectangle according to the specified grafvert). 

Procedure StdRRect (verb: Graf Verb; r: Rect; ovalwidth,ovalHeight: 
integer); 

StdRRect is the standard low-level routine for drawing a rounded-corner 
rectangle. It draws the given rounded-corner rectangle according to the 
specified grafverb. Ovaiwidth and ovalHeight specify the diameters of 
curvature for the comers. 

Procedure StdOval (verb: Graf Verb; r: Rect); 

StdOval is the standard low-level routine for drawing an oval. It draws an 
oval inside the given rectangle according to the specified grafVeib. 

Procedure StdArc (verb: GrafVerb; r: Rect; startAngle,arcAngle: 
integer); 

StdArc is the standard low-level routine for drawing an arc or a wedge. It 
draws an arc or wedge of the oval that fits inside the given rectangle. The 
grafVfeit) specifies the graphic operation; if it's the frame operation, an arc is 
drawn; otherwise, a wedge is drawn. 

Procedure StdPoly (verb: GrafVerb; poly: PolyHandle); 

StdPoly is the standard low-level routine for drawing a polygon. It draws the 
given polygon according to the specified grafVertx 

Procedure StdRgn (verb: GrafVerb; rgn: RgnHandle); 

StdRgn is the standard low-level routine for drawing a region. It draws the 
given region according to the specified grafVerb. 
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Procedure StcBlts (var srcBlts: BltMap; var srcRect,clstRect: Rect; 
mode: integer; maskRgn: RgnHandle); 

stdBiU is the standard low-level routine for doing bit transfer. It transfers a 
bit image between the given bitmap and thePort ^xjrtBlts, just as if CopyBits 
were called with the same parameters and with a destination bitmap equal to 
triePort"4X)rtBils. 

Procedure stdConinent (klnd,datasize: integer; dataHandle: ODHandle); 

StdComment is the standard low-level routine for processing a picture 
comment. Kind Identifies the type of comment. DataHandle is a handle to 
additional data, and dataSize is the size of that data in bytes. If there Is no 
additional data for the command, dataHandle will be nil and dataSize will be 
0. StdComment simply ignores the comment. 

Function stdTxrieas (bytecount: integer; textBuf : QOPtr; var numer, 
denom: Point; var info: Fontlnfo) : integer; 

StdTxMeas is the standard low-level routine for measuring text width. It 
returns the width of the text stored in the arbitrary structure in memory 
specified by textBuf, starting with the first byte and continuing for DyteCount 
bytes. Numer and denom specify the scaling as in the StdText procedure; note 
that StdTxMeas may change them. 

Procedure StdGetPic (dataPtr: QOPtr; bytecount: integer); 

StdGetPic is the standard low-level routine for retrieving Information from 
the definition of a picture. It retrieves the next bytecount bytes from the 
definition of the currently open picture and stores them in the data structure 
pointed to by dataPtr. 

Procedure StdPutPic (dataPtr: QOPtr; bytecount: integer); 

StdPutPic is the standard low-level routine for saving information as the 
definition of a picture. It saves as the definition of the currently open 
picture the drawing commands stored in the data structure pointed to by 
dataPtr, starting with the first byte and continuing for the next byteCount 
bytes. 
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E.11 Using QuickDraw from Assembly Language 

All QuickDraw routines can be called from assembly-language programs as 
well as from Pascal. When you write an assembly-language program to use 
these routines^ though, you must emulate Pascal's parameter passing and 
variable transfer protocols. 

This section discusses how to use the QuickDraw constants, global variables, 
data types, procedures, and functions from assembly language. 

The primary aid to assembly language programmers is a file named 
QD/GRAFTYPES.TEXT. If you use .INCLUDE to include this file when you 
assemble your program, all the QuickDraw constants, offsets to locations of 
global variables, and offsets into the fields of structured types will be 
available in symbolic form. 

E.11.1 constanu 

QuickDraw constants are stored in the QD/GRAFTYPES.TEXT file, and you 
can use the constant values symbolically. For example. If you've loaded the 
effective address of the thePort".txMode field into address register A2, you 
can set that field to the srcxor mode with this statement: 

MOVE.i #SRCX0R,(A2) 

To refer to the number of bytes occupied by the QuickDraw global variables, 
you can use the constant GRAFSIZE. When you call the initGraf procedure, 
you must pass a pointer to an area at least that large. 

E.ll^ Data Types 

Pascal's strong typing ability lets you write Pascal programs without really 
considering the size of a variable. But in assembly language, you must keep 
track of the size of every variable. The sizes of the standard Pascal data 
types are as follows: 



Type 


Size 


integer 


word (2 bytes) 


longint 


Long (4 bytes) 


boolean 


Word (2 bytes) 


char 


word (2 bytes) 


real 


Long (4 bytes) 



integers and longlnts are In two's complement form; booleans have their 
boolean value in bit 8 of the word (the low-order bit of the byte at the same 
location); Chan are stored in the high-order byte of the word; and reals are in 
the KCS standard formaL 
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The QuickDraw simple data types listed below are constructed out of these 
fundamental types. 



Type 


size 


CJDPtl 


Long (4 bytes) 


QDHandle 


Long (4 bytes) 


word 


Long (a bytes) 


Str255 


Page (256 bytes) 


Pattern 


8 bytes 


Bitsie 


32 bytes 



Other data types are constructed as records of variables of the above types. 
The size of such a type is the sum of the sizes of all the fields in the record; 
the fields appear In the variable with the first field in the lowest address. 
For example^ consider the data type BitMap, which is defined as follows: 

type Bithap = record 

baseAddr: QDPtr; 
rowBytes: integers- 
bounds: Rect 
end; 

This data type would be arranged in memory as seven words: a long for the 
baseAddr, a word for the rowBytes, and four words for the top, left, right, and 
bottom parts of the bounds rectangle. To assist you in referring to the fields 
inside a variable that has a structure like this, the GJDA3RAFTYPES.TEXT file 
defines constants that you can use as offsets into the fields of a structured 
variable. For example, to move a bitmap's rowBytes value into D3, you would 
execute the following instruction: 

MOVE.W riYBITHAP+R0«BYTES,D3 

Displacements are given in the QD/GRAFTYPES.TEXT file for all fields of all 
data types defined by QuickDraw. 

To do double indirection, you perform an LEA indirectly to obtain the 
effective address from the handle. For example, to get at the top coordinate 
of a region's enclosing rectangle: 

MOVE.L MYHANDLE,A1 ; Load handle into Al 

rioVE.L (A1),A1 ; Use handle to get pointer 

MOVE.* RGNBBOX+T0P(Al),D3 ; Load value using pointer 
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For regions (and all other variable-length structures with handles), you 
must not move the pointer into a register once and just continue to use 
that pointer; you must do the double indirection each time. Every 
QuickDraw call you make can possibly trigger a heap compaction that 
renders all pointers to movable heap items (like regions) invalid. The 
handles will remain valid, but pointers you've obtained through handles 
can be rendered invalid at any subroutine call or trap in your program. 

E.11.3 Global variolas 

Register A5 always points to the section of memory where global variables 
are stored. The GJD/GRAFTYPES.TEXT file defines a constant GRAFGLOB 
that points to the beginning of the QuickDraw variables in this space, and 
other constants that point to the individual variables. To access one of the 
variables, put GRAFGLOB in an address register, sum the constants, and index 
off of that register. For example, if you want to know the horizontal 
coordinate of the pen location for the current grafPort, which the global 
variable thePort points to, you can give the following instructions: 

ttOVE.L GRAFGLC6(A5),A0 ; Point to QuickDraw globals 
riOVE.L THEP0RT(A0),A1 ; Get current grafPort 

MOVE.W PNL0C*H(A1),D0 ; Get thePort^.pnLoc.h 

E.11.4 Procedures and Functions 

To call a QuickDraw procedure or function, you must push all parameters to it 
on the stack, then JSR to the function or procedure. When you link your 
program with QuickDraw, these JSRs are adjusted to refer to QuickDraw's 
Jump table, so that a JSR into the table redirects you to the actual location 
of the procedure or function. 

The only difficult part about calling QuickDraw procedures and functions Is 
stacking the parameters. You must follow some strict rules: 

• Save all registers you wish to preserve before you begin pushing 
parameters. Any QuickDraw procedure or function can destroy the 
contents of the registers AO, Al, DO, Dl, and D2, but the others are never 
altered. 

• Push the parameters in the order that they appear In the Pascal procedural 
Interface. 

• For booleans, push a byte; for Integers and characters, push a word; for 
pointers, handles, long Integers, and reals, push a long. 

• For any structured variable longer than 4 bytes, push a pointer to the 
variable. 
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• For all var parameters, regardless of size, push a pointer to the variable. 

• When calling a function, first push a null entry equal to the size of the 
function result tfien push all other parameters. The result will be left on 
the stack after the function returns to you. 

This makes for a lengthy interface, but it also guarantees that you can mock 
up a Pascal venlon of your program, and later translate it into assembly code 
that works the same. For example, the Pascal statement 

blackness := GetPixel(50,inousePos.v); 

would be written in assembly language like this: 

; Save space for tK)olean result 

; Push constant 50 (decimal) 

; Push the value of inousePos.v/ 

; Call routine 

; Fetch result from stack 

This is a simple example, pushing and pulling word-long constants. Normally, 
you'll be pushing more pointers, using the PEA (Push Effective Address) 
instruction: 

FillRoundRect(iiiyRect, l, thePort" .pnSlze. v, i»hite); 

Push pointer to royRect 
Push constant 1 
Point to QuickDraw globals 
Get current grafPort 
Push value of thePorf.pnSize.v 
Push pointer to global variable white 
Call the subroutine 

To call the TextFace procedure, push a word in which each of seven bits 
represents a stylistic variation: set bit for bold, bit 1 for italic, bit 2 for 
underline, bit 3 for outline, bit 4 for shadow, bit 5 for condense, and bit 6 for 
extend. 



CLR.K 


-(SP) 


MOVE.i 


#50, -(SP) 


MOVE.H 


MOUSEPOS+V,-(SP) 


JSH 


GETPIXEL 


MOVE.i 


(SP)+, BLACKNESS 



novE.w 


il,-(SP) 


mvE.L 


GRAFGL0B(A5),A0 


riOVE.L 


THEPORT(AO),A1 


MOVE.i 


PNSIZE+V(A1), -(SP) 


PEA 


l!HITE(AO) ; P 


JSR 


FILLROUNDRECT 
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E.12 Graf3D: TTiree-Dlmenslonal Graphics 

Graf3D helps you map three-dimensional images onto the two-dimensional 
space used Dy QuickDraw. If this is your first exposure to three-dimensional 
graphics, you will find Graf3D's standard procedures and functions a great help 
in producing visually exciting graphs, charts, and drawings. If you are familiar 
with Applegraphics for the Apple II, you will feel right at home with Graf3D's 
use Of real variaoies and world coordinates. 

With three-dimensional graphics you can present objects In true perspective, 
which will evoke for users their everyday environment Graf3D helps you 
represent complex business information pictorlaliy; for example, a manager can 
see important relationships among sales, profits, and advertising dollars in a 
three-dimensional graph. 

You may be interested in a more theoretical discussion of three-dimensional 
graphics, including an explanation of some of the basic concepts of Graf3D, 
such as the viewing pyramid. A good, illustrated discussion appears in the 
section on three-dimensional computer graphics In Principles of interactive 
Computer Graphics by William M. Newman and Robert F. Sproull (New York: 
McGraw-Hill, 1973). 

E.12.1 HOW Graf3D is Related to QuickDraw 

Graf3D is a Pascal unit that makes the QuickDraw calls necessary to produce 
three-dimensional graphics. It provides you with an easy-to-use real number 
interface to QuickDraw's Integer coordinates. You could, of course, write 
your own QuickDraw calls to perform the same functions Graf3D provides for 
you, but that would be a little like going to the trouble of writing your own 
compiler. 

E.12.2 Features of Graf3D 

• A caniera-eye View. This allows you to set the point of view from which 
the observer sees the object independently from the coordinates of the 
object itself. The camera is set up with the Viewport, LookAt, and 
ViewAngle procedures. You can set the focal length of the camera as if 
you had a choice of telephoto, wide angle, or normal lenses. 

• Tniee-dlmensional clipping t£) a tjve pyramid The apex of the pyramid is 
at the point of the camera eye, and the base of the pyramid is equivalent 
to the Viewport. When you use the Clip3D function, only objects forward 
of the camera eye and within the pyramid are displayed on the screen. 

• Two-aimenslonal point and line capability using real coordinates. Graf 3D 
provides commands corresponding to the QuickDraw commands but using 
real coordinates Instead of Integers. With real coordinates you have a 
larger dynamic range for graphics calculations; with Integer coordinates 
you get faster drawing time. For reals, the range is 

1.4 x 10"^^ to 3.4 X 10^^ 
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• Two-aimer>slonal or tJiree-ciImenslonal rotation. You can rotate an object 
along any or all axes simultaneously, using the Pitcn, Yaw, and Roll 
procedures. 

• Translation and scaling of objects In one or more axes simultaneously. 
Translation means movement anywhere in three-dimensional space. Scaling 
means shrinking or expanding. 

E.12.3 Graf3D Data Types 

Graf3D declares and uses the following data types: 

Polnt3D: A Polnt3D contains three real numoer coordinates: x, y, and z. 

Graf3D uses x, y, and 2 for real number coordinates to distinguish 
between the h and v integer screen coordinates in QuickDraw. 

Polnt2D: A Point2D is just like a Polnt3D but contains only x and y 
coordinates. 

XfMatrlx: The XfMatrix is a 4x4 matrix of real values, used to hold a 

transformation equation. Each transforming routine alters this 
matrix so that it contains the concatenated effects of all 
transformations applied. 

Poit3DPtr: A Port3DPtr is a pointer to a Port3D. 

Port3D: A Port3D contains all the state variables needed to map real 

number coordinates into integer screen coordinates. They are as 
follows: 

C^ort: a pointer to the grafPort associated with this Port3D. 

viewRect: the viewing rectangle within the grafPort; the base of the 
viewing pyramid. 

xLeft, yTqa, xRight, yBottom: world coordinates corresponding to 
the ViewRect 

pen: three-dimensional pen location. 

perPrime: the pen location transformed by the xForm matrix. 

eye: three-dimensional viewpoint location established by ViewAngle. 

hSize, vSize; half-width and half-height of the viewRect in screen 
coordinates. 

hCenter, vCenter: center of the viewRect in screen coordinates. 

xCotan, yCotan: viewing cotangents set up by ViewAngle, used Ky-^ 
Clip3D. 

ident: a boolean that allows the transformation to be skipped when 
when xForm is an Identity matrix. 

xForm: a 4x4 matrix that holds the net result of all transformations. 
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E.12.4 Graf3D Procedures and Functions 

The following procedures and functions are provided In Graf5D. 

Procedure 0pen30Port(port: Port3DPtr); 

0pen3DPort initializes all the fields of a Port3D to their defaults^ and makes 
that Port3D the current one. Gport is set to the currently open grafPort. 
The defaults established are: 

thePort3D:=port; 
port* . GPort : = thePort; 
Vle«»Port(thePort\portRect); 

•ITH thePort'.portRect DO LookAt(left, top, right, Dottom); 
Vle»Angle(0); 
Identity; 
MoveTo3D( 0,0,0); 

Procedure SetPort3D(port: Port30Ptr); 

SetPort3D makes port the current Port3D and calls SetPort for that Port3D*s 
associated grafPort. SetPort3D allows an application to use more than one 
Pon3D and switch between them. 

Procedure GetPort3D(var port: Port3DPtr); 

GetPort3D returns a pointer to the current Port3D. This procedure is useful 
when you are using several Port3Ds and want to save and restore the current 
one. 

Procedure rioveTo20(>cy: real); Procedure MoveTo30()cy^z: real); 
Procedure riove2D(dx,dy: real); Procedure nove3D(d)cdy,dz: real); 

These procedures move the pen In two or three dimensions without drawing 
lines. The real number coordinates are transformed by the xForm matrix and 
projected onto flat screen coordinates; then Graf3D calls QuickDraw's MoveTo 
procedure with the result. 

Procedure LineTo20(>cy: real); Procedure LineTo3D()cy,z: real); 
Procedure Llne20(dx,dy: real); Procedure Llne3D(dx,dy,dz: real); 

These procedures draw two- and three-dimensional lines from the current pen 
location. LineToZD and LineZD stay on the same z-plane. The real number 
coordinates are first transformed by the xForm matrix, then clipped to the 
viewing pyramid, then projected onto the flat screen coordinates and drawn by 
calling QuickDraw's LlneTo procedure. 
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Function Cllp3D(srcLsrc2: Point30; var dstl,clst2: Point): txxjlean; 

Clip3D Clips a tnree-dlmenslonal line segment to tne viewing pyramid and 
returns the clipped line projected onto screen coordinates. Clip3D returns 
true if any part of the line is visible. If no part of the line is within the 
viewing pyramid, Cllp3D returns false. 

Procedure SetPt3D(var pt3D: Point3D; x,y,z: real); 

SetPt3D assigns three real numbers to a Polnt3D. 

Procedure setPt2D(var pt2D: Polnt20; x,y: real); 

SetPt2D assigns two real numbers to a Point2D. 

E.1Z4.1 Setting Up the Camera (Viewport^ LookAt, and VlewAngle) 

Procedures Viewport, LookAt and ViewAngle position the image in the 
grafPort, aim the camera, and choose the lens focal length in order to map 
three-dimensional coordinates onto the flat screen space. These procedures 
may be called in any order. 

Procedure Viei»Port(r: Rect); 

Viewport specifies where to put the image in the grafPort. The Viewport 
rectangle is in integer QuickDraw coordinates, and tells where to map the 
LookAt coordinates. 

Procedure LookAt(left,top^ right, bottom: real); 

LookAt specifies the real number x and y coordinates corresponding to the 
vlewRect 

Procecftjre y/le«Angle(angle: real); 

ViewAngle controls the amount of perspective by specifying the horizontal 
angle (in degrees) subtended by the viewing pyramid. Typical viewing angles 
are 0° (no perspective), 10** (telephoto lens), 25" (normal perspective of the 
human eye), and 80** (wide angle lens). 

£.13.0.2 The Transfonnation Matrix 

The transformation matrix allows you to impose a coordinate transformation 
between the coordinates you plot and the viewing coordinates. Each of the 
transformation procedures concatenates a cumulative transformation onto the 
xForm matrix. Subsequent lines drawn are first transformed by the xForm 
matrix, then projected onto the screen as specified by Viewport, LookAt, and 
ViewAngle. 

Procedure Identity; 

Identity resets the transformation matrix to an identity matrix. 



E-78 



Pascal Reference Manual QuickDraw 

Procedure Scale(xFactor.yFactor,zFactor: real); 

Scale modifies the transformation matrix so as to shrink or expand by xFactor, 
yFactor^ and zFaotor. For example^ Scale(2.0^.0^.0) will make everything 
come out twice as big when you draw. 

Procedure Translate(d)cdy,dz: real); 

Translate modifies the transformation matrix so as to displace by djcdy/lz. 

Procedure Pitch(xAngle: real); 

Pitch modifies the transformation matrix so as to rotate xAngle degrees 
around the x axis. A positive angle rotates clockwise when looking at the 
origin from positive x 

Procedure Yaw(yAngle: real); 

Yaw modifies the transformation matrix so as to rotate yAngle degrees around 
the y axis. A positive angle rotates clockwise when looking at the origin 
from positive y. 

Procedure Roll(zAngle: real); 

Roll modifies the transformation matrix so as to rotate zAngle degrees around 
the z axis. A positive angle rotates clockwise when looking at the origin 
from positive z. 

Procedure Ske«(zAngle: real); 

Skew modifies the transformation matrix so as to skew zAngle degrees 
around the z axis. Skew only changes the x coordinate; the result is much 
like the slant QuickDraw gives to italic characters. (Skew(15.0) makes a 
reasonable Italic.) A positive angle rotates clockwise when looking at the 
origin from positive z. 

Procedure TransFonn(src: Point3D; var dst: Point30); 

Transform applies the xForm matrix to src and returns the result as dst If 
the transformation matrix is identity, dst will be the same as src 
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E.13 QuickDraw Interface 

UNIT QuickDraw; 

{ Copyright 1983 Apple computer Inc. } 
INTERFACE 



CONST srccopy 


= 0; 


srcOr 


= 1; 


srcXor 


= 2; 


srcBic 


= 3; 


notSrcCopy 


= 4; 


notSrcOr 


= 5; 


notsrcxor 


= 6; 


notSrcBlc 


= 7; 


patCopy 


= 8; 


patOr 


= 9; 


patxor 


= 10; 


patBlc 


= 11; 


notPatCopy 


= 12; 


notPator 


= 13; 


notPatxor 


= 14; 


notPatBlc 


= 15; 


{ QuickDraw color 


separat 


normalBlt 


= 0; 


inverseBit 


= 1; 


redBit 


= 4; 


greenBit 


= 3; 


DlueBit 


= 2; 


cyanBit 


= 8; 


magentaBit 


= 7; 


yellowBit 


= 6; 


blackBit 


= 5; 


dlackColor 


= 33; 


whiteColor 


= 30; 


redColor 


= 205; 


greenColor 


= 341; 


blueColor 


= 409; 


cyanColor 


= 273; 


magentaColor 


= 137; 


yellowColor 


= 69; 



{ the 16 transfer modes } 



{ normal screen mapping } 
{ inverse screen mapping } 
{ RGB additive mapping } 



{ CMYBk subtractive mapping } 



{ colors expressed in these mappings } 



picLParen = 0; 
picRParen = 1; 



{ standard picture comments } 
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TYPE QOByte 


= 


-128.. 127; 


QOPtr 


= 


"OOByte; { blind pointer } 


OOHandle 


= 


^ODPtr; { blind handle } 


Str255 


= 


String[255]; 


Pattern 


= 


PACKED ARRAY[0..7] OF 0..255; 


Bitsie 


= 


ARRAY [0.. 15] OF INTEGER; 


VHSeiect 


= 


(V.h); 


GrafVerb 


= 


(f rame^ paint, erase, invert, f ill ); 


Stylelten 


- 


(bold, italic, underline, outline, shadow, condense, 
extend); 


style 


= 


SET OF Styleltenu 


Fontlnfo 




RECORD 

ascent: INTEGER; 

descent: INTEGER; 

widMax: INTEGER; 

leading: INTEGER; 
END; 


Point = RECORD CASE INTEGER OF 




0: 


(v: INTEGER; 




h: 


INTEGER); 



1: (Vh: ARRAY [VHSeiect] OF INTEGER); 
END; 



Rect = RECORD CASE INTEGER OF 



0: (top: 
left: 
bottom: 
right: 



INTEGER; 
INTEGER; 
INTEGER; 
INTEGER); 



END; 



(topLeft: Point; 
botRight: Point); 
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Bltriap = RECORD 

baseAddr: OOPtr; 
rowBytes: INTEGER; 
bounds: Rect; 
END; 



Cursor = RECORD 

data: Bitsl6; 
mask: Bitsl6; 
hotSpot: Point; 
END; 



Penstate = RECORD 

pnLoc: Point; 

pnSize: Point; 

pnnode: INTEGER; 

pnPat: Pattern; 
END; 



PolyHandle = "PolyPtr; 
PolyPtr = ^Polygon; 
Polygon = RECORD 

polySize: INTEGER; 
polyBBox: Rect; 
polyPoints: ARRAY [0..0] OF Point; 
END; 



RgnHandle = ^RgnPtr; 
RgnPtr = "Region; 
Region = RECORD 

rgnsize: INTEGER; { rgnSize = 10 for rectangular } 

rgnBBox: Rect; 

{ plus nore data if not rectangular } 

END; 



PicHandle = 


TlcPtr; 


PlcPtr 


Cloture; 


Picture = 


RECORD 




picSize: INTEGER; 




picFrame: Rect; 




{ plus byte codes for picture content } 




END; 
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ODProcsPtr = "QDProcs; 




QDProcs = RECIM) 




textProc: 


OOPtr; 


lineProc: 


QDPtr; 


rectProc: 


ODPtr; 


rRectProc: 


QDPtr; 


ovalProc: 


OOPtr; 


arcProc: 


OOPtr; 


polyProc: 


OOPtr; 


rgnProc: 


OOPtr; 


bitsProc: 


ODPtr; 


coiwnentProc: 


ODPtr; 


txMeasProc: 


OOPtr; 


getPlcProc: 


OOPtr; 


putPicProc: 


OOPtr; 


END; 




GrafPtr = "GrafPort; 




GrafPort = RECORD 




device: 


INTEGER; 


portBits: 


Bitnap; 


portRect: 


Rect; 


visRgn: 


RgnHandle; 


clipRgn: 


RgnHandle; 


dkPat: 


Pattera* 


fillPat: 


Pattern; 


pnLoc: 


Point; 


pnSize: 


Point; 


pnrtode: 


INTEGER; 


pnPat: 


Pattern; 


pnVis: 


INTEGER; 


txFont: 


INTEGER; 


txFace: 


Style; 


txflode: 


INTEGER; 


txSize: 


INTEGER; 


spExtra: 


Longint; 


fgColor: 


Longint; 


bkColor: 


Longint; 


colrBit: 


INTEGER; 


patStretch: 


INTEGER; 


picSave: 


OOHandle; 


rgnSave: 


ODHandle; 
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polySave: 
grafProcs: 
END; 



OOHandle; 
QOProcsPtr; 



VAR thePort: 


GrafPtr; 


white: 


Pattern- 


black: 


Pattern; 


gray: 


Pattern; 


ItGray: 


Pattern; 


dkGray: 


Pattern; 


arrow: 


Cursor; 


screenBits: 


BitMap; 


randSeed: 


Longint; 



{ GrafPort Routines } 



PROCEDURE initGraf 


(glot)alPtr: QDPtr); 


PROCEDURE OpenPort 


(port: GrafPtr); 


PROCEDURE InitPort 


(port: GrafPtr); 


PROCEDURE ClosePort 


(port: GrafPtr); 


PROCEDURE SetPort 


(port: GrafPtr); 


PROCEDURE GetPort 


(VAR port: GrafPtr); 


PROCEDURE GrafDevice 


(device: INTEGER); 


PROCEDURE SetPortBits 


(bm: BitMap); 


PROCEDURE PortSize 


(width, height: INTEGER); 


PROCEDURE MOVePortTO 


( lef tGlodal, topGlobal : INTEGER) 


PROCEDURE SetOrigin 


(h^v: INTEGER); 


PROCEDURE SetCllp 


(rgn: RgnHandle); 


PROCEDURE GetClip 


(rgn: RgnHandle); 


PROCEDURE ClipRect 


(r: Rect); 


PROCEDURE BackPat 


(pat: Pattern); 


{ Cursor Routines } 




PROCEDURE InltCursor; 




PROCEDURE SetCursor(crsr: Cursor); 


PROCEDURE HideCursor; 




PROCEDURE ShowCursor; 




PROCEDURE OdscureCursor; 
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{Line Routines } 

PROCEDURE HidePen; 
PROCEDURE ShOWPen; 

PROCEDURE GetPen (VAR pt: Point); 
PROCEDURE GetPenState(VAR pnstate: PenState); 
PROCEDURE SetPenState(pnState: PenState); 

PROCEDURE PenSize (width, height: INTEGER); 

PROCEDURE PenMode (mode: INTEGER); 

PROCEDURE PenPat (pat: Pattern); 
PROCEDURE PenNormal; 

PROCEDURE MoveTo (h,v: INTEGER); 

PROCEDURE Move (dh.dv: INTEGER); 

PROCEDURE LineTo (h,v: INTEGER); 

PROCEDURE Line (dh.dv: INTEGER); 



{ Text Routines } 



PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 

FUNCTION 



TextFont 

TextFace 

TextMode 

TextSize 

SpaceExtra 

DrawChar 

Drawstring 

DrawText 

CharWidth 

stringWidth 

TextWidth 



PROCEDURE GetFontlnfo 



(font: INTEGER); 

(face; Style); 

(mode: INTEGER); 

(size: INTEGER); 

(extra: Longint); 

(ch: char); 

(s: Str255); 

(textBuf: QDPtr; firstByte.byteCount: INTEGER); 

(ch: CHAR): INTEGER; 

(S: Str255): INTEGER; 

(textBuf: ODPtr; firstSyte^byteCount: INTEGER) 

INTEGER; 
(VAR info: Fontlnfo); 



{ Point Calculations } 



PROCFDURE 


ArtdPt 


PROCEDURE SudPt 


PROCEDURE 


SetPt 


FUNCTION 


EqualPt 


PROCEDURE 


ScalePt 


PROCEDURE 


riapPt 


PROCEDURE LocalToGlobal 


PROCEDURE GlOdalToLocal 



(src: Point; VAR dst: Point); 
(src: Point; VAR dst: Point); 
(VAR pt: Point; h^v: INTEGER); 
(ptl,pt2: Point): BOaEAN; 
(VAR pt: Point; 
(VAR pt: Point; 
(VAR pt: Point); 
(VAR pt: Point); 



f romRect, toRect : Rect ); 
fron«ect,toRect: Rect); 
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{ Rectangle Calculations } 

PROCEDURE setRect (VAR r: Rect; left, top, rlgnt^Dottom: integer); 

FUf€TION EqualRect (recti, rect2: Rect): BOOLEAN; 

FUNCTION EnptyRect (r: Rect): BOOLEAN; 

PROCEDURE Off setRect (VAR r: Rect; dh,dV: INTEGER); 

PROCEDURE HapRect (VAR r: Rect; f romRect, toRect : Rect); 

PROCEDURE InsetRect (VAR r: Rect; Clh,ClV: INTEGER); 

FUNCTION SectRect (srci,src2: Rect; VAR dstRect: Rect): BOOLEAN; 

PROCEDURE UnlonRect (srci,src2: Rect; VAR dstRect: Rect); 

FUNCTION PtInRect (pt: Point; r: Rect): BOOLEAN; 

PROCEDURE Pt2Rect (ptl,pt2: Point; VAR dstRect: Rect); 



{ Graphical operations on Rectangles } 

PROCEDURE FrajieRect (r: Rect); 

PROCEDURE PaintRect (r: Rect); 

PROCEDURE EraseRect (r: Rect); 

PROCEDURE InvertRect (r: Rect); 

PROCEDURE FillRect (r: Rect; pat: Pattern); 



{ RoundRect Routines } 



PROCEDURE FraroeRoundRect 
PROCEDURE PaintRoundRect 
PROCEDURE EraseRoundRect 



(r: Rect; 

(r: Rect; 

(r: Rect; 

PROCEDURE InvertRoundRect (r: Rect; 
PROCEDURE FillRoundRect (r: Rect; 



OVWd,ovHt: INTEGER); 
0Vlld,0VHt: INTEGER); 
0V»d,0VHt: INTEGER); 
OVWd,OVHt: INTEGER); 
ov«d,ovHt: INTEGER; pat: Pattern); 



{ Oval Routines } 

PROCEDURE Frameoval (r: Rect); 

PROCEDURE PaintOval (r: Rect); 

PROCEDURE Eraseoval (r: Rect); 

PROCEDURE InvertOval (r: Rect); 

PROCEDURE FillOval (r: Rect; pat: Pattern); 



{ Arc Routines } 

PROCEDURE FrameArc (r: Rect; 

PROCEDURE PaintArc (r: Rect; 

PROCEDURE EraseArc (r: Rect; 

PROCEDURE InvertArc (r: Rect; 



startAngle,arcAngle: INTEGER); 
startAngle,arcAngle: INTEGER); 
start Angle, arcAngle : INTEGER ); 
startAngle, arcAngle : INTEGER ); 
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PROCEDURE FillArc (r: Rect; startAngle^arcAngle: INTEGER; pat: 

Pattsm) * 
PROCEDURE PtToAngle (r: Rect; 'pf- Point; VAR angle: INTEGER); 



{ Polygon Routines } 



FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 



(^jertPoly: 

ClosePoly; 

KillPoly 

OffsetPoly 

MapPoly 

FraniePoly 

PaintPoly 

ErasePoly 

InvertPoly 

FillPoly 



PolyHandle; 



(poly 
(poly 
(poly 
(poly 
(poly 
(poly 
(poly 
(poly 



PolyH^Tdle) * 

PolyHandle; 'dh^dv: INTEGER); 

PolyHandle; fron«ect/toRect: Rect); 

PolyHandle); 

PolyHandle); 

PolyHandle); 

PolyHandle); 

PolyHandle; pat: Pattern); 



{ Region Calculations } 



FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 

FUNCTION 

FUNCTION 



NewRgn: RgnHandle; 

DisposeRgn(rgn: RgnHandle); 

CopyRgn (srcRgn^dstRgn: RgnHandle); 

SetEwptyRgn(rgn: RgnHandle); 

SetRectRgn(rgn: RgnHandle; left, top^ right, bottom: INTEGER); 



(rgn: RgnHandle; r: Rect); 
(dstRgn: RgnHandle); 



RectRgn 

OpenRgn; 

CloseRgn 

OffsetRgn (rgn: RgnHandle; dh^dv: INTEGER); 



riapRgn (rgn: RgnHandle; f roraRect, toRect 

InsetRgn (rgn: RgnHandle; dh^dv: INTEGER); 

SectRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 

UnionRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 

DiffRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 

xorRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 

EqualRgn (rgnA,rgnB: RgnJtendle): BOOLEAN; 

EnptyRgn (rgn: RgnHandle): BOOLEAN; 

PtInRgn (pt: Point; rgn: RgnHandle): BOOLEAN; 

RectlnRgn (r: Rect; rgn: RgnHandle): BOOLEAN; 



Rect); 



{ Graphical Operations on Regions } 



PROCEDURE FrameRgn 
PROCEDURE PaintRgn 
PROCEDURE EraseRgn 



(rgn: RgnHandle); 
(rgn: RgnHandle); 
(rgn: RgnHandle); 
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PROCEDURE invertRgn (rgn: RgnHandle); 

PROCEDURE FlllRgn (rgn: RgnHandle; pat: Pattern); 



{ Graphical Operations on BitMaps } 

PROCEDURE ScrollRectCdstRect: Rect; dh^dV: INTEGER; updateRgn: 

rgnHandle); 
PROCEDURE CopyBitS (srcBltS.dStBitS: BltMap; 

srcRectydstRect: Rect; 

mode: INTEGER; 

maskRgn : RgnHandle ); 

{ Picture Raitines } 

FUNCTION OpenPicture(picFrame: Rect): PicHandle; 

PROCEDURE ClosePicture; 

PROCEDURE OrawPicture(myPicture: PicHandle; dstRect: Rect); 

PROCEDURE PicConment(kind.dataSize: INTEGER; dataHandle: QDHandle); 

PROCEDURE KillPicture(niyPicture: PicHandle); 



{ The Bottleneck Interface: } 



PROCEDURE 
PROCEDURE 

PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 

PROCEDURE 
PROCEDURE 
PROCEDURE 

PROCEDURE 
FUNCTION 



PROCEDURE 
PROCEDURE 



SetStdProcs(VAR procs: (JOProcs); 

StdText (count: INTEGER; textAddr: QOPtr; numer^denom: 

Point); 
StdLlne (newPt: Point); 
StdRect (verb: Graf Verb; r: Rect); 
StdRRect (verb: Graf Verb; r: Rect; ovWd^ovHt: INTEGER); 
StdOval (verb: Graf verb; r: Rect); 
StdArc (verb: Graf Verb; r: Rect; startAngle^arcAngle: 

INTEGER); 
StdPoly (verb: Graf Verb; poly: PolyHandle); 
StdRgn (verb: Graf Verb; rgn: RgnHandle); 
StdBits (VAR srcBits: BitMap; VAR srcRect^dstRect: Rect; 

mode: INTEGER; maskRgn: RgnHandle); 
StdComment (kind^dataSize: INTEGER; dataHandle: QDHandle); 
StdTxMeas (count: INTEGER; textAddr: ODPtr; 

VAR numer^denom: Point; 

VAR info: Fontlnfo): INTEGER; 
StdGetPic (dataPtr: QDPtr; byteCount: INTEGER); 
StdPutPic (dataPtr: QDPtr; byteCount: INTEGER); 
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{ Mlsc Utility Routines } 

FUNCTION GetPlxel (h.v: INTEGER): BOOLEAN; 
FUNCTION Random: INTEGERS- 
PROCEDURE Stuff Hex (tningptr: OOPtr; s:Str255); 
PROCEDURE ForeColor (color: Longint); 
PROCEDURE BackColor (color: LongInt); 
PROCEDURE ColorBlt (wnlchBlt: INTEGER); 

E.13.1 Giraf3D Interface 

{$S Graf } 

UNIT Graf3D; 

{ three-dimensional graphics routines layered on top of QuickDraw } 

INTERFACE 

USES {$U OD/QuickDraw.OBJ } QuickDraw; 

CONST radConst =57. 29578; 

TYPE Point3D=REC0RD 

x: REAL; 
y: REAL; 
z: REAL; 
END; 

Point2D=REC0RD 

x: REAL; 
y: REAL; 
END; 

Xf Matrix = ARRAY [0.. 3,0,. 3] OF REAL; 
Port30Ptr « "Port30; 
Port3D = RECORD 

GPort: GrafPtr; 

vlewRect: Rect; 

xLef t^ yTop, xRights yBottom : REAL; 

pea penPrime, eye : Polnt3D; 

hSize,vSi2e: REAL; 

hCenter,vCenter: REAL; 

xCotan^ yCotan : REAL; 

Ident: BOOLEAN; 

xForm: Xf Matrix; 
END; 
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VAR thePort30: Port30Ptr; 



PROCEDURE 0pen30Port 
PROCEDURE SetPort3D 
PROCEDURE GetPort3D 



(port: Port30Ptr); 
(port: Port3DPtr); 
(VAR port: Port30Ptr); 



PROCEDURE MoveTo2D(x,y: REAL); 

PROCEDURE LineTo20(X,y: REAL); 

PROCEDURE hove2D(cl>CCly: REAL); 

PROCEDURE Line2D(cl)CCly: REAL); 



PROCEDURE ri0VeT03D(>^y^Z: REAL); 

PROCEDURE LineT03D(>cy.Z: REAL); 

PROCEDURE hove3D(cl)CCly^dZ: REAL); 

PROCEDURE Line3D(clx,cly,dZ: REAL); 



PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
FUNCTION 



Viewport 

LOOkAt 

VlewAngle 

Identity; 

Scale 

Translate 

Pitch 

Yaw 

Roll 

Skew 

TransForm 

Clip30 



PROCEDURE SetPt3D 
PROCEDURE SetPtZD 



(r: Rect); 

( lef t^ top, right, bottom : RE AL ); 

(angle: REAL); 

(xFactor, yFactor, zFactor : REAL ); 
(djcdy.dz: REAL); 
(xAngle: REAL); 
(yAngle: REAL); 
(zAngle: REAL); 
(zAngle: REAL); 

(src: Point3D; VAR dst: Point3D); 
(srcl,src2: Point3D; VAR dsti,d8t2: 
BOOLEAN; 

(VAR pt3D: Point30; JCy^Z: REAL); 
(VAR pt2D: Point2D; X,y: REAL); 



POINT) ; 
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E.14 QidckOraw Sample Programs 

This section provides listings of two sample programs that are included with 
the Workshop software. 

E.14.1 QDSample 

The program QDSample (In the file QDA3DSample.TEXT) demonstrates 
different things that QuickDraw can da Its output is shown in Figure E-26. 



look whot you can dra^ M^ith QuickOraM' 



Text 

Bold 

Italic 
Underline 




Rectangles 




RoundRects 




Bit Images 






ip [p 



k^edges 




Polygons 




Regions 



Ok'als 



Arbitrary Clippipfl-SjMio> 

Irbitr/ V:ii|f pr 

Irbif \jfk ior 

^r\/ wntpri^ior 



R rumui y Liipp ing Regior 

^rhihrnrii Tlinninn Danitv' 




Figure E-26 
QDSample 

The file QD/?^l/QDSample.TEXT is an exec file that can be used to rebuild 
this sample program. Disregard any warning messages from the linker about 
name conflicts. 
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PROGRAM QDSanple; 

{ Sample program illlustratlng the use of QuickDraw. } 

USES {$U QD/QulckDraw.OBJ } QuickDraw. 
{$U (^/QOajpport.reJ } QDSuj^rt; 

TYPE ICOnData = ARRAY[0. .95] OF INTEGER; 

VAR heapBuf: ARRAY [0.. 10000] OF INTEGER; 
myPort: Graf Port; 
icons: ARRAY [0.. 5] OF iconOata; 



FUNCTION HeapFull(hz: QOPtr; bytesNeeded: INTEGER): INTEGER; 

{ this function will be called if the heapzone runs out of space } 

BEGIN 

WRITELN('The heap is full. The program must now terminate! '); 

Halt; 
END; 



PROCEDURE Initlcons; 

{ Manually stuff some icons. 

BEGIN 



Normally we would read them from a file } 



{ Lisa } 

StuffHex(aicons[0, 0]. 
StuffHex(aicons[0, 12], 
Stuf f Hex(aicons[ 0, 24], 
StuffHex(aicons[0,36], 
StuffHex(aicons[0, 48], 
Stuf fHex(aicons[a 60], 
StuffHex(aicons[0, 72], 
StuffHex(aicons[0, 84], 



• OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOIFFFFFFFFC ' ); 
' 0060000000060180000000080600000000130FFFFFFFFFA3' ); 
• 18000000004311FFFFF00023120000080F231200000BF923' ); 
' 120000080F23120000080023120000080023120000080F23' ); 
' 1200000BF923120000080F2312000008002311FFFFF00023' ); 
• 08000000004307FFFFFFFFA30100000000260FFFFFFFFE2C' ); 
• 18000000013832AAAAA8A9F0655555515380C2AAAA82A580' ); 
• 800000000980FFFFFFFFF300800000001600FFFFFFFFFCOO ' ); 



{ Printer } 

StuffHex(aicons 

StuffHex(aicons 



StuffHex(aiconsfl,24 



StuffHex(aicons 
StuffHex(aicons 
StuffHex(aicons 
StuffHex(aicons 
StuffHex(aicons 



1. 
1,12 



1,36 
1,48 
1,60 
1,72 
1,84 



, '000000000000000000000000000000000000000000000000' ); 
, •00000000000000007FFFFF00000080000280000111514440' ); 
, '0002000008400004454510400004000017C00004A5151000' ); 
' 0004000010000004A54510000004000017FEOOF4A5151003' ); 
, •0184000013870327FFFFF10F06400000021B0CFFFFFFFC37' ); 
, ' 18000000006B300000QOOOD77FFFFFFFFFABC00000000356' ); 
, •8000000001AC87F000000158841000CCC1B087FOOOCCC160' ); 
, •8000000001C0C000000003807FFFFFFFFF0007800001E000' ); 



E-92 



Pascal Reference Manual QuickDraw 

{ Trash Can } 

Stuff Hex(aicons[2, 0]. ' 000001FCOOOOOOOOOE0600000000300300000000C0918000' ); 
Stuff Hex(alcons[2, 12], •00013849800000026C4980000004C0930000000861260000* ); 
StuffHex(alcons[2, 24], '0010064FE0000031199830000020E6301800002418E00800' ); 
Stuff Hex(aiC0ns[2, 36], •0033E3801C0000180E002COOOOOFF801CC0000047FFEOCOO' ); 
Stuff Hex(aicons[2, 48], •000500004C000005259A4C000005250A4C00000525FA4COO' ); 
StuffHex(aicons[2, 60], '000524024C00000524924C00600524924C0090E524924C7C" ); 
StUffHex(aicons[2, 72], •932524924C82A44524924001C88524924CF10C4524924C09' ); 
Stuff Hex(aicons[2, 84], ■0784249258E70003049233100000EOOOE40800001FFFC3FO' ); 

{ tray } 

StUf f Hex(aicons[ 3, ], ' 000000000000000000000000000000000000000000000000 • ); 
stuff Hex(aicons[3, 12], '0000000000000000000000000000000000000007FFFFFFFO' ); 
StUffHex(aicons[3, 24], ' 000E00000018001A00000038003600000O78006A000000O8 ' ); 
Stuff Hex(aicons[3, 36], '00O7FFFFFFB801AC0000O358035800O006B807FC000FFD58' ); 
StUffHex(aicons[3, 48), ' 040600180AB80403FFF00058040000000AB8040000000058' ); 
Stuff Hex(aicons[3, 60], ' 040000000AB807FFFFFFFD5806ACOOOOOAB8055800000D58 * ); 
StUffHex(aicons[3, 72], •06B000000AB807FC000FFD70040600180AE00403FFF00DC0' ); 
Stuff Hex(aicons[3, 84], •040000000B80040000000F00040000000E0007FFFFFFFCOO* ); 

( Fll6 Cadinst } 

StUffHex(alcons[4, 0], ■0007FFFFFC00000800000C00001000001C00002000003400' ); 
Stuff Hex(aicons[4, 12], •004000006COOOOFFFFFFD40000800000ACOOOOBFFFFED400' ); 
StUffHex<alcons[4, 24], ' OOAOO002AC0000A07F02D4O00OA041O2ACO00OA07F02D400' ); 
Stuff Hex(aicons[4, 36], ■OOA00002ACOOOOA08082D40000AOFF82ACOOOOA00002D400' ); 
Stuff Hex(alcons[4, 48], •0OA00002AC0O00BFFFFED4000O8000O0ACO000BFFFFEO40O' ); 
Stuff Hex(aicons[4, 60], ' OOA00002ACOOOOA07F02D40000A04102ACOOOOA07F02D400' ); 
StUffHex(alcons[4, 72], '00A0O002AC00O0A08O82D4000OA0FF82ACO00OAOOOO2D800' ); 
Stuff Hex(aicons[4, 84], •O0AO0002BO0OO0BFFFFEE0000O8O00O0COOO0OFFFFFF8000' ); 

{ drawer } 

Stuff Hex(alC0ns[5, 0], '000000000000000000000000000000000000000000000000' ); 
stuff Hex(aicons[5, 12], '000000000000000000000000000000000000000000000000' ); 
stuff Hex(alcons[5, 24], '000000000000000000000000000000000000000000000000' ); 
stuff Hex(aicons[5, 36], 'OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOIFFFFFFO' ); 
stuff Hex(aicons[5, 48], ' 0000380000300000680000700000D8000000003FFFFFF1BO' ); 
StUf fHex(aicons[5, 60], ' 0020000013500020000016B000201FE01D50002010201A80' ); 
StUffHex(alcons[5, 72], '00201FE01560002000001AC0002000001580002020101BOO' ); 
Stuff Hex(aicons[5, 84], '00203FF01600002000001C00002000001800003FFFFFFOOO' ); 

END; 



E-93 



Pascal Reference Manual QuickDraw 

PROCEDURE Drawlcon(whichlcoah,v: INTEGER); 
VAR srcBits: BitMap; 

srcRect^dstRect: Rect; 
BEGIN 

srcBits . baseAddr : =aicons [ whlcnicxjn ]; 

srcBlts . rowBytes : »6; 

SetRect(srcBlts. bounds^ 0^ 0^ 48^ 32); 

srcRect : =srcBlts . bounds; 

dstRect:=srcRect; 

Of f setRect(dstRect^ X\, v); 

CopyBltsC srcBits^ thePort " . portBlts, srcRect, dstRect^ srcOr^ Nl 1 ); 
END; 

PROCEDURE DrawStUf f; 

VAR 1: INTEGER; 
tenpRect: Rect; 
myPoly: PolyHandle; 
myRgn: RgnHandle; 

mypattern: Pattern; 

BEGIN 
stuff Hex(5NnyPattern. '8040200002040800'); 

tenpRect := thePort^.portRect; 
clipRect(tei?pRect); 
EraseRoundRect(teinpRect^ 50^ 20); 
FrameRoundRect(teni)Rect^ 30^ 20); 

{ draw tw) rwrizontal lines across the top } 

rioveTo(0^ 18); 

LineTo(719. 18); 

MoveTo(0,20); 

LlneTo(719.20); 

{ draw divider lines } 
«oveTo(0^ 134); 
LineTo(7l9. 134); 
M0VeT0( 0,248); 
LlneT0(719.248); 
hOVeTo(240,21); 
LlneTo(24a 363); 
HoveTo(480,21); 
LlneTo(480, 363); 
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{ draw title } 

TextFont(O); 

MoveTo(210. 14); 

DrawStringCLook what you can draw with QuickDraw'); 



{ draw text sanples 

MoveTo(80, 34); DrawString( ' Text ' ); 

TextFace([bold]); 

Mo\/eTo(70, 55); DrawString( ' Bold ' ); 

TextFaceC [ italic ] ); 

MoveTo(70, 70); OrawString( ' Italic ' ); 

TextFace( [underline ] ); 

MoveTo(70, 85); OrawString( ' Underline* ); 

TextFaceC [outline] ); 

MoveTo(70, 100); OrawString( ' Outline ' ); 

TextFace( [ shadow ] ); 

MoveTo(70, 115); DrawString( ' Shadow ' ); 

TextFaceC []); { restore to normal } 



{ draw line sswples 

MoveToC330^ 34); Or awStringC 'Lines' ); 

MoveToC280,25); LineCl60,40); 

PenSizeC3.2); 

MoveToC280, 35); LineCl60, 40); 

PenSi2eC6, 4); 

riOveToC280,46); LineC160,40); 

PenSizeCl2,8); 
PenPatCgray); 
MoveToC280,61); LineCl60.40); 
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PenSize(15,10); 
PenPat (myPattern ); 
MoveTo(28a 80); Line( 160, 40); 
PenNormal; 



{ draw rectangle samples } 

MoveTo(560, 34); DrawString( ' Rectangles ' ); 

SetRect(tenpRect, 510, 40, 570, 70); 
FraneRect(tempRect); 

Of f setRect(tempRect, 25, 15); 
PenSi2e(3, 2); 
EraseRect ( tenpRect ); 
Fr ameRect ( tenpRect ); 

Of f setRect(tenpRect, 25, 15); 
PaintRect ( tempRect ); 

Of f setRect(tenpRect, 25, 15); 

PenNormal; 

F 11 lRect( tempRect, gray); 

FrameRect ( tempRect ); 

Of f setRect(tempRect, 25, 15); 
FillRect( tempRect, myPattern); 
FrameRect ( tempRect ); 

{ draw roundRect samples } 

MoveTo(70, 148); DrawString( ' RoundRect s ' ); 

SetRect(tempRect, 30, 150, 90, 180); 
FrQmoRounclRoot(toiFpRoot, 30, 20); 

Of f setRect(tempRect, 25, 15); 
PenSize(3,2); 

EraseRoundRect(tempRect, 30, 20); 
FranieRoundRect(tem|3Rect, 30, 20); 

Of f setRect(tempRect, 25, 15); 
PalntRoundRectC tempRect, 3D, 20); 
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Of f setRect(teinpRect, 25, 15); 
PenNormal; 

FillRoundRect(tef?pRect, 30, 20, gray); 
FrameRoundRect ( tempRect, 30, 20 ); 

Off setRect(tempRect,25, 15); 
FillRoundRect(teirpRect, 30, 20, myPattern); 
FrafneRotnclRect(tempRect, 30, 20); 

{ draw bit image samples } 

rioveTo(320, 148); DrawString('Bit Images'); 

Drawlcon(0,266,156); 
DrawIcon(l,336,156); 
DrawIcon(2, 406, 156); 
DrawIcon(3,266,196); 
DrawIcon(4, 336, 1%); 
DrawIcon(5, 406, 1%); 

{ draw Wedge samples } 

HoveTo(570, 148 ); DrawString( ' Wedges * ); 

SetRect(tenpRect, 520, 153, 655, 243); 
FillArc(tefl(pRect, 135, 65, dkGray ); 
FillArc(tefnpRect, 200, 130, myPattern); 
FillArc(tempRect, 330, 75, gray); 
FrameArcCtempRect, 135,270); 
Of f setRect(tenpRect, 20, 0); 
PaintArc(tenpRect, 45, 90); 



{ draw polygon samples 



MoveTo(80, 262); DrawString( ' Polygons ' ); 
myPoly:=OpenPoly; 

MoveTo(30,290); 

LineTQ(30,280); 

LineTo(50,265); 

LineTo(90,265); 

LineTo(80, 280); 

LineTo(95,290); 

LineTo(30,290); 
ClosePoly; { end of definition } 
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FramePoly (myPoly ); 

Of f setPolyCmyPoly, 25, 15); 
PenSize(3, 2); 
ErasePoly ( myPoly ); 
FramePoly(nyPoly); 

Of f setPoly(tnyPoly, 25, 15); 
PaintPoly(inyPoly); 

Of f setPoly(myPoly, 25, 15); 

PenNormal; 

FillPoly (myPoly, gray); 

FramePoly(myPoly); 

Of f setPoly(myPoly, 25, 15); 
FillPoly(myPoly, myPattern); 
FramePoly (myPoly ); 

KillPoly (myPoly); 



{ demonstrate region clipping } 

HoveTo(320, 262); DrawString( ' Regions ' ); 

myRgn:=Ne«Rgn; 
Oper^gn; 
ShowPen; 

SetRect(tempRect, 260, 270, 460, 350); 
FrameRoundRect(tenpRect, 24, 16); 

rioveTo(275, 335); { define triangular hole } 

LineT0(325,285); 

LineTo(375,335); 

LineT0(275, 355); 

SetRect(tempRect,365,277,445,325); { oval hole } 
FrameOval ( tempRect ); 

HidePen; 
CloseRgn(myRgn); { end of definition } 

3etClip(myRgn); 
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FOR i:=0 TO 6 00 { draw stuff inside the clip region } 
BEGIN 

MoveTo(260,280+12M); 

DrawStringC Arbitrary Clipping Regions'); 
EhD; 

ClipRectCthePort'^ .portRect); 
DisfX)seRgn(myRgn); 

{ draw oval sanples } 

MoveTo(580, 262); DrawString( ' Ovals ' ); 

SetRect(tenpRect, 510. 264, 570, 294); 
FrameOval ( tenpRect ); 

Of f setRect(tempRect, 25, 15); 
PenSize(3, 2); 
EraseOval(ternpRect); 
FrameOval ( tefflfrf^ect ); 

Of f setRect(tefipRect, 25, 15); 
PaintOval ( tenfMRect ); 

Of f setRect(tempRect, 25, 15); 

PenNormal; 

F i 1 lOval ( tenpRect, gray ); 

FrameOval ( tenpRect 



f: 



Of f setRect(tempRect, 25, 15); 
F i 1 lOval ( tempRect, myPattern ); 
FrameOval ( tempRect ); 
END; { DrawStuff } 
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BEGIN { main program } 
{ Initialization - Generic to all applications using QuickDraw } 
QOInit(aheapBuf, aheap8uf[ 10000], aHeapFull); { Must do this once at 

beginning } 
OpenPort(5NnyPort); 
PaintRect(thePort".portRect); { Paint grey backgromd } 

Initlcons; 
DrawStuff; 
Tone(200D, 500); { Beep tone of (1/2000)*10"6 == 500 cycles/sec for 

500 milliseconds } 
ReadLn; { Wait until RETLRN entered before terminating program ) 
END. 
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E.142 Boxes 

The program Boxes (in the file QD/Boxes.TEXT) uses the Graf3D routines to 
draw random three-dimensional boxes on a grid, as shown in Figure E-27. 




Figure E-27 
Boxes 

The file QD/M/Boxbs.TEXT is an exec file that can be used to rebuild this 
sample program. Disregard any warning messages from the linker about name 
conflicts. 
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PROGRAM Boxes; 

{ Sample program illustrating use of the Graf3D unit by drawing random 
3D ix)xes on a grid. } 

USES 

{$U QO/QuickOraw.OBJ } QuickDraw^ 

{$U Q0/6raf3D.0a3 } Graf 30, 

{$U 0D/Q0Support.C8J } ODSupport, 

CONST boxCount = 15; 

TYPE Box3D=REC0RD 





ptl: P0int3D; 




pt2: P0lnt3D; 




dist: REAL; 




END; 


VAR 




heapBuf: 


ARRAY [0.. 8192 3 OF INTEGER; 


GPortl: 


Graf Port; 


6Port2: 


Port3d; 


myPort: 


GrafPtr; 


inyPort30 


: Port3DPtr; 


boxArray 


: ARRAY [0..bOXCount] OF B0X3D; 


nBoxes: 


INTEGER; 


i: 


INTEGER; 



{16k bytes} 



FUNCTION HeapError(hz: QDPtr; bytesNeeded: INTEGER): INTEGER; 
{ this procedure gets called when the heap zone is full } 
BEGIN 

WRITELNC'The heap is full. The program must now terminate! '); 

HALL- 
END; 



FUNOTION Dl8tonoe(ptl,pt2: P0INT3D): REAL; 

VAR d>cdy,dz: REAL; 
BEGIN 

dx:=pt2.X - ptl.X; 

dy:=pt2.Y - ptl.Y; 

dZ:=pt2.Z - ptl.Z; 

Distance :=SQRT(dx«dx + dy*dy + dz*dz); 
END; 
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PROCEDURE MakeBox; 



VAR myBox: 


B0X3D; 


i,j,h,v: 


INTEGER; 


P1.P2: 


Point3D; 


myRect: 


Rect; 


testRect: 


Rect; 


BEGIN 




pi. x: "Random mod 70-15; 


pl.y:=Random mod 70 -10; 


pl.z:»0.0; 




p2.X:=pl.X * 


10 ♦ ABS(Random) MOD 30; 


p2.y:=pl.y ^ 


10 * ABS(Random) MOD 45; 


p2.z:=pl.2 + 


10 + ABS(Random) MOO 35; 



{ reject t)ox If it intersects one already in list } 
SetRect(myRect, ROUND(pl .x), ROUND(pl .y), R0UND(p2 .x), R0UN0(p2.y ) ); 
FOR i:=0 TO nBoxes-1 DO 
BEGIN 
WITH boxArray[i] DO 
SetRect( testRect, R0UN0(ptl .x), ROUNO(ptl .y ), 
R0UND(pt2 . x), R0UN0(pt2 . y ) ); 
IF SectRect(myRect, testRect, testRect) THEN EXIT (MakeBox); 
END; 

myBox.ptl:=pl; 
myBox.pt2:=p2; 

{ calc midpoint of box stkI its distance from the eye } 

pl.x:=(pl.x + p2.x)/2.0; 

pl.y:=(pl.y * p2.y)/2.0; 

pl.2:=(pl-Z + p2,z)/2.0; 

Transf orm(pl, p2); 

myBox. dist:=Distance(p2,myPort3D''. eye); { distance to eye } 

i:=0; 

boxArray[nBoxes].dist:-myBox.dist; { sentinel } 

WHILE myBox. dist > boxArray[i].dist DO i:=i+l; {insert in order of dist} 
FOR j:»nBoxes DOWNTO i+1 DO boxArray[j]:»boxArray[j-l]; 
boxAr ray [ i ] : =myBo>c 
nBoxes : =nBoxes* 1; 
END; 
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PROCEDURE DrawBox(pttpt2: Point30); 
{ clra«»s a 30 box with shaded faces. } 
{ only shades correctly in one direction } 
VAR tenpRgn: RgnHandle; 



{ front face, y=yl } 



{ top face, z=z2 } 



BEGIN 
tempRgn:=NewRgn; 
OpenRgn; 
MoveTo30(ptl .x, ptl .y, ptl .z); 
LineTo30(pt l . x, pt l . y, pt2 . z ); 
LineTo30(pt2.x, ptl .y, pt2.z); 
LineTo3D(pt2.x,ptl.y,ptl.z); 
LineTo30(ptl .X, ptl .y, ptl .z); 
CloseRgn(te^^pRgn); 
FillRgn(tempRgn, white); 

OpenRgn; 

MoveTo30(pt 1 . x, ptl . y, pt2 . z ); 

LineTo3D(pt 1 . x, pt2 . y, pt2 . z ); 

LineTo30(pt2.x, pt2.y,pt2.z); 

LineTo3D(pt2 . x, ptl . y, pt2 . z ); 

LineTo30(ptl.>^ ptl .y, pt2.z); 
CloseRgn(teiipRgn); 
FillRgn(ten|)Rgn, gray); 



Opertf^gn; 

MoveTo3D(pt2.x,ptl.y,ptl.z); { right face, x=x2 } 

LineTo30(pt2.x,ptl.y,pt2.z); 

LineTo3D(pt2 . x, pt2 . y, pt2 . z ); 

LineTo3D(pt2.x, pt2.y,ptl .z); 

LineTo30(pt2.x, ptl .y,ptl .z); 
CloseRgn( telnpRgn ); 
FillRgnCtenpRgn, black); 



PenPat(white); 

MoveTo30(pt2 . >^ pt2 .y, pt2 . z); 
LlneTo3D(pt2.x, pt2.y, ptl .z); 
LineTo30(pt2 . x, ptl .y, ptl . z); 
PenNormal; 

Oi sposeRgnC tempRgn ); 



{ outline right } 



END; 
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BEGIN { main program } 
{ Initialization - Generic to all applications using QuickDraw } 
ODInit(aheapBuf, aheapBuf [8192], sheapError); { Must do this once at 

beginning ) 

myPort := aOPortl; 
(^jenPor t ( myPort ); 
myPort3D := 86Port2; 
0pen3DPor t ( myPor t3D ) ; 

ViewPort(myPort" .portRect); { (X»t the image in this rect } 

LookAt(-100,75, 100, -75); { aim the camera into 3D space } 

Vie«Angle(30); { choose lens focal length } 

Identity; Roll(20); Pitch(70); { roll and pitch tfb plane } 

PenPat( white); 
BackPat (black); 
EraseRect(myPort" .portRect); 

FOR i:=-10 TO 10 DO 
BEGIN 

MoveTo3D(i*10, -100, 0); 

LineTo30(i*10, +100, 0); 
END; 

FOR i:=-10 TO 10 DO 
BEGIN 

ttoveTo3D(-100, i*10, 0); 

LineTo3D(+100, i*10, 0); 
END; 

nBoxes:=0; 

REPEAT MakeBox; UNTIL nBoxes=boxCount; 
FOR i:=n8oxes-l DOWNTO DO 
DrawBox(boxArray[i] .ptl, boxArray[i ] .pt2); 

Tone(2000, 500); {Beep tone of (1/2000)*10*6 == 500 cycles/sec for 

500 milliseconds } 
ReadLn; { Wait until RETIRE entered before terminating program } 

END. 
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E.1S QOSupport 

The QDSupport unit (in the file QDA^DSupportTEXT) provides the 
initialization that you need to use QuickDraw in the QDlnit procedure^ as well 
as procedures for simplified access to mouse tracking, the mouse button^ and 
sound generation, and useful definitions of font numbers. For more detailed 
information on mouse-handling routines and sound, refer to /Appendix F, 
Hardware interface. 

UNIT QDSupport; 

INTERFACE 

USES 



{$u Q0/UnltStd.08J } UnitStd, 


{$U QD/UnitHz.OBJ 


} UnitHz, 


{$U QO/Hardware.OBJ } Hardware, 


{$U QO/Fontmgr.C©J > Fontmgr, 


{$U (30/QuickDraw.OBJ ) QuickDraw; 


CONST 

/ 


_ Cnn+ Kh t 


»i^^-»» 1 


1 


rOnX NUiiiJcid / 


FTllelZ 


= 4; 


{proportional} 


FTileia 


= 5; 


{proportional} 


FTile24 


= 6; 


{proportional} 


FPlSTile 


= 7; 


{Monospaced - 8 lines/inch & 15 chars/inch} 


FPlZTile 


= 8; 


{Monospaced - 6 lines/inch 8t 12 chars/inch} 


FPlOTile 


= 9; 


{Monospaced - 6 lines/inch & 10 chars/inch} 


FCentl2 


= 10; 


{proportional 


FCentl8 


= 11; 


{proportional 


FCent24 


= 12; 


{proportional} 


FP12Cent 


= 13; 


{Monospaced - 6 lines/inch & 12 chars/inch} 


FPlOCent 


= 14; 


{Monospaced - 6 lines/inch a 10 chars/inch} 


FP20Tlle 


= 19; 


{Monospaced} 
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PROCEDURE QOInit(startPtr, limitPtr: QDPtr; ErrorProc: QOPtr); 
{ QOInit: Initializes QuickDraw unit by setting up its heap 

zone, global vars, cursor, and the Font Manager it 

calls on. } 

PROCEDURE GetMouse(VAR pt: Point); 

{ GetMouse: Returns the current mouse location in the local 
coordinates of the current grafPort. } 

FUNCTION MouseButton: BOOLEAN; 

{ MouseButton: Returns TRUE if the mouse button is currently held 
down, otherwise FALSE. } 

PROCEDURE Tone(waveLength, duration: Longint); 

{ Tone: Produces a square wave tone of the specified 

wavelength (microseconds) for the specified duration 

(milliseconds). } 
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E.16 Glossary 

bit image: A collection of bits in memory that have a rectilinear represen- 
tatioa The Lisa screen is a visible bit image. 

bitmap: A pointer to a bit image, the row width of that image, and its 
bouTKlary rectaigle. 

boundary rectangle: A rectangle defined as part of a bitmap, which encloses 
the active area of the bit image and imposes a coordinate system on it Its 
top left comer is always aligned around the first bit in the bit image. 

cameza eye: A cor^^ept in three-dimensional graphics: the point of view and 
the viewir^ angle in which an rt)Ject e^apears, irwlependent of the crtjject's 
coordinates. 

character style: A set of stylistic variations, such as bold, italic, and 
underline. The empty set indicates normal text (no stylistic variations). 

clipping: Limiting drawing to within the bounds of a particular area 

clipping region: Sarr« as clipRga 

clipRgn: Tr« region to which an application limits drawing in a grafPort. 

coonfinate plane: A two-dimensional grid. In QuickDraw, the grid coordinates 
are integers ranging from -32768 to +32767, and all grid lir^s are infinitely 
thin. 

cursor A 16-by- 16-bit image that ap|[ears cmi the screen and is controlled by 
the mouse. 

cursor level: A value, initialized to when the system is booted, that keeps 
track of the number of times the cursor has been hiddea 

empty: Containing no bits, as a shape defined by only one poinL 

font The complete set of characters of one typeface, such as Century. 

frame: To draw a shape by drawing an outline of iL 

global coordinate system: The coordinate system based on the top left comer 
of the bit image being at (0J3)l 

Graf3D: A three-dimensional graphics unit that calls QuickDraw routines. 

grafPort: A corrplete drawing envirorMnent, including such elements as a 
bitmap, a subset of it in which to draw, a character font, patterns for drawing 
and erasing, and other pen charajteristics. 

grafPtr A pwinter to a grafPort. 

handle: A pointer to one master pointer to a dynamic, relocatable data 
structure (such as a region). 

hotspot Tt« point in a cursor that is aligied with the mouse positioa 

kem: To stretch part of a character back under the previous character. 
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local coordinate system: The coordinate system local to a grafPort^ imposed 
by the boundary rectangle defined in its bitmap. 

missing symbol: A character to be drawn in case of a request to draw a 
character that is missing from a particular font 

pattern: An 8-by-8-bit image^ used to define a repeating design (such as 
stripes) or tone (such as gray). 

pattern transfer mode: One of eight transfer modes for drawing lines or 
sh^Des with a pattern. 

picture: A saved sequence of QuickDraw drawing commands (and, optionally, 
picture correrents) that yew can play boik later with a single procedure call; 
also, the image resulting from these commands. 

picture comments: Data stored in the definition of a picture which does not 
affect the picture's appearance but may t« used to provide additional 
information about the picture wf«n it's played back. 

picture frame: A rectangle, defined as part of a picture, which surrounds the 
picture and gives a frame of reference for scaling when the picture is drawn. 

pixel: The visual representation of a bit on the screen (white if the bit is 0, 
black if it's 1). 

point The intersection of a horizontal grid line and a vertical grid line on 
the coordinate plane, defined by a horizontal and a vertical coordinate. 

polygon: A sequence of connected lines, defined by QuickDraw line-drawing 
commands. 

port GrafPort or Port3D. 

Port3D: A data structure in Graf3D that maps three-dimensional coordinates 
into a two-dimensional QuickDraw grafPort. 

Poit3DPtK A pointer to a Port3D. 

portBits: The bitmap of a grafPort 

portBltsinunds: The boundary rectangle of a grafPort's bitmap. 

portRect A rectangle, defined as part of a grafPort, which encloses a subset 
of tl^ bitm^ for use by the grafPort 

region: An arbitrary area or set of areas on the coordinate plane. The 
outline of a region should be one or more closed loops. 

row width: The nuntoer of bytes in each row of a bit image. 

scale: To shrirt< or expand by a specified factor. 

solid: Filled in with any pattern. 

source transfer mode: One of eic^t transfer modes for drawing text or 
transferring any bit image between two bitmaps. 
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style: See character style. 

thePort: A global variariDle that points to the current grafPort 

thePort3D: A global variable that points to the current Port3D, 

transfer mode: A s|:«cification of which bcx»lean deration G^JickDraw shcwld 
perform when drawing or when transferring a bit image from one bitmap to 
another. 

translate: To move in three-dimensional space by a specified amount 

transformation matrix: Same as xForm matrix 

viewing pyrandd: The portion of three-dimensional space that a camera eye 
can see. The pyramid's apex |s the point of the camera eye; its base is the 
viewRect in a Port3D. 

visRgn The region of a grafPort which is actually visible on the screea 

xFonn matrix: A ax4 matrix that holds an equation to transform points 
plotted in three-dimensional coordinates into two-dimensional screen 
coordinates. 
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Hardware Interface 



The hardware interface software provides an interface for accessing and 
controlling several parts of the Lisa hardware. The hardware/software 
capabilities addressed include the mouse, the cursor, the display, the contrast 
control, the speaker, txjth Lndecoded and decoded keyboard ax«ss, the micro- 
second and millisecond timers and the hardware clodc/calendar. 

This afipendix contains Pascal procedure and function declarations interleaved 
with text describing them. Pascal type cteclarations and a summary of the 
function and procedure declarations can be found in Section F.IO, Interface of 
the Hardware Unit 

Programs using this unit should be conpiled against the file C^/l-fardware.C)BJ 
and linked to the file QD/HWIntL.OBJ. 

F.1 TTw Mouse 
F.1.1 Mouse Location 

Procedure MouseLocation (var x Pixels; var y: Pixels); 

The mouse is a pointing device used to indicate screen locations. 
MouseLocation returns the location of the mouse. The X-coordinate can range 
from to 719, and the Y-coordinate from to 363. The initial mouse 
location is OA 

F.1.2 Mouse Update Frequency 

Procedure MouseUpdates (delay: MilliSecGnds); 

Software knowledge of the mouse location is i^xlated periodically, rather than 
contimously. The frequency of these updates can be set by callir^ 
MouseUpdates. The time between updates can range from milliseconds 
(continuous updating) to 28 milliseconds, in intervals of 4 milliseconds. The 
initial setting is 16 milliseconds. 

F.1.3 Mou% Scaling 

Procedure MouseScaling (scale£oolean); 

Procedure MouseThresh (threshold: PixelsX' 

The relationship tietween physical mouse movements and logical mouse move- 
ments is not necessarily a fixed linear mapping. Three alternatives are 
available: 1) unsealed, 2) scaled for fine movement and 3) scaled for coarse 
movement Initially mouse movements are unsealed. 

When mouse movement is unscaJed a horizontal mouse movement of x units 
yields a char^ in the mouse X-coordinate of x pixels. Similiarly, a vertical 
rrxwement of y units yields a change is the mouse Y-coordinate of y pixels. 
These rules apply independent of the speed of the mouse movement 
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Wtien nxxise movennent is scaiecL horizontal movements are magnified by 3/2 
relative to vertical movements. This is to compensate for the 2/3 aspect 
ratio of pixels on the screen. When scaling is in effect, a distinction is made 
between fine (small) movements and coarse (large) movements. Fine move- 
ments are slightly reduced, while coarse movements are magnified. For scaled 
fine movements^ a horizontal mouse movement of x units yields a change in 
the x-coordinate of x pixels, but a vertical movement of y units yields a 
change of (2/3)*y pixels. For scaled coarse movements, a horizontal movennent 
a X units yields a change of (3/2)»x pixels, while a vertical movements of y 
units yields a change of y pixels. 

The distinction between fine movements and coarse movements is determined 
by the sum of the x and y movements each time the mouse lo^tion is 
updated. If this sum is at or below the threshoJci the movement is considered 
to be a fine movement Values of the threstnld range from (which yields all 
coarse movements) to 256 (whit^ yields all fine nrovementsX Given the 
default mouse updating frequency, a threshold of about 8 (threshold's initial 
setting) gives a comfortable transition between fine and coarse movements. 

MouseScaling enables and disables mouse scaling. Mouseinresh sets the 
threshold between fine and coarse movements. 

F.1.4 Mouse Odometer 

Function MouseOdometen ManyPixels; 

In order to properly specify, design and test mice, it's important to estimate 
how far a mouse moves during its lifetime. MouseOdometer returns the sum 
of the X and Y movements of the mouse since boot time. The value returned 
is in (unsealed) pixels. There are 180 pixels per \viA\ of mouse movement 

?2 TheCXnrsor 

Procedure Cuiwrlmage (hotX: Pixels; holY: Pixels; height: CursoiHeight; data: 
CunoiPtr; mask: CursoiPtr); 

The cursor is a small image that is displayed on the screea Its shape is 
specified by two bitmaps, called tiata and mask These bitmaps are 16 bits 
wide and from to 32 bits high. The rule used to combine the bits already 
on the screen with the data and mask is 

screen <- (screen and (not mask^ xor data. 

The effect is that white areas of the screen are replaced with the cursor 
data Black areas of the screen are replaced with (not mask) xor data If the 
data and mask bitmaps are identical, the effect is to or the data onto the 
screen. 

The cursor has both a location and a hotspot The location is a position on 
the screen, with X-coordinates of to 719 and Y-coordinates of to 363. 
The hotspot is a position within the cursor bitmaps, with X- and Y-coordi- 
nates ranging from to 16. The cursor is displayed on the screen with its 
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hotspot at its location. If tfie cursor's location is near an edge of the screen, 
the cursor image may be partially or completely off the screen- 
Most cursor operations can be performed by calling the SetCursor, HfideCiirsor, 
ShowCXirsor, and GbscureCXorsor proceckjres defined by QuickDraw (see Section 
E.9.2, Cursor-Handling Routines). Additional capabilities are provided by the 
Hardware Interface routines described below. 

The Cursorlmage procedure is used to specify the data bitmap, mask bitm^, 
height and hot^wt of the cursor. Initially the cursor data and mask bitmaps 
contain all zeros, which yields a blank (invisible) cursor. The initial hotspot is 
0,0. 

F.2.1 CursorA'iGuse Tracking 

Procedure (XDraorTracking (track: Boolean); 

Procedure CursoiLocatian (x: Pixels; y: Pixels); 

CursorTracking enables and disables cunor tracking of the mouse. When 
tracking is endDled, the cursor location is changed to U^ mouse location each 
time the mouse moves. Setting the cunor location by calling CursorLocation 
will have no effect; the cursor sticks with the mouse. 

When tracking is disabled, the mouse locatiwi axl cursor location are inctepen- 
dent Callir^ CursorLocation will move the cursor; moving the mouse will not 

When tracking is first enabled (i.e., ai each transition from disabled to 
enabled) the mouse location is modified to equal the cursor location. There- 
fore, enabling tracking does not move the cursor; it does modify the mouse 
location. Initially tracking is enabled. 

F.2.2 TTk Busy Cursor 

Procedure Busylmage (hotX: Pixels; holY: Pixels; height: CursorHeight; data: 
CursorPtr; mask: CursorPtr); 

Procedure BusyOelay (delay: Milliseconds); 

Aiplications may desire to display a tjusy cursor (e.g., an hourglass) when an 
operation in progress requires more than a few seconds to complete. The 
Busylmage procedure is used to specify the data bitmap, mask bitm^, height 
and hotspot of the busy cursor. 

A call to BusyDelay specifies that the normal cursor should currently be 
displayed, aid that display of the txisy cursor strauld be delayed for Vn& 
specified nunr^Der of milliseconds. SidDsequent calls to BusyCielay overricte 
previous calls, postponing display of tr« busy cursor. If no calls to BusyOelay 
occur for the sf»cified rajirtf^r of millisecarKls, the tMJsy cursor will be 
displayed until the next call to BusyDelay. 

Initially the busy cursor data and mask bitmaps contain all zeros, which yields 
a blank (invisible) cursor. The initial hotspot is OA The initial busy delay is 
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infinite, that is, the busy cursor will not be displayed until BusyOelay is 
called. 

F3 The Display Screen 

Procedure ScreenSize (var x: Pixels; var y: Pixels); 

The display screen is a tit m^^Ded dispJay/ that is, each pixel on the screen 
is controlled by a bit in main memory. 'Vne display has 720 pixels horizontally 
and 364 lines vertically, ar«j therefore requires 32,760 bytes of main memory. 
The screen size may be determined by calling ScreenSize. 

Function FrameCounter: Frames; 

The screen is redisplayed ^x)ut 60 times per second. A fl'&Tje counter is 
incremented between screen updates, at the vertical retrace interrupt The 
freme comter is an unsigned 32-bit integer which is reset to each time the 
machirw is booted. FrameCounter returns this value. An application can 
synchronize with the vertical retraces by watching for changes in the value of 
this coLBiter. The frame counter should iwt be used as a timer; use the 
millisecond and mircosecond timers instead. 

F.3.1 Screen Contrast 

Function Contrast: ScreenContrast; 

Procedure SetContrast (contrast: ScreenContrast); 

The display's contrast level is iffider program control. Contrast values raige 
from to 255 ($FF), with as maximum contrast and 255 as minimum. 
Contrast returns the contrast setting; SetContrast sets the screen contrast. 
The low orcter two bits of the contrast value are igiored. Tte initial contrast 
value is 128 ($80)l 

Procedure RampContrast (contrast: ScreenContrast); 

A sudden change in the coitrast level can te jarring to the user. 
RampContrast gradually changes the contrast to the new setting over a pericKJ 
of stfxxjt a second. RampContrast returns immediately, then ramps the 
contrast using interrupt driven processir^ 

F.3.2 Automatic Screen Fading 

Function DimContrast: ScreenContrast; 

Procedure SetDimContiast (contrast: ScreenContrast); 

The screen contrast level is automatically dimmed if no user activity is noted 
over a specified period (usually several mimtes). This is done in orcter to 
preserve the screen pho^aher. DimContrast returns the contrast value to which 
the screen is dimmed; SetCKmContrast sets this valie. The initial dim 
contrast setting is 176 ($80). 
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Function FadeOelay: NfiUiSecxinds; 

Procedure SetFadeOelay (delay: I^UiSeconds); 

The delay between tlie last user activity and dimming of the screen is under 
software control. FadeOelay returns the fade delay; SetFadeOelay sets it 
The actual delay will range from the specified delay to twice the specified 
delay. The initial delay period is five minutes. 

When the screen is dim, user interaction will cause the screen contrast to 
return to its normal bright level (determined by the Contrast and SetContrast 
rojtines defined above). Moving the mouse or pressing a key on the keyboard 
(e.g., SHIFT) is enough to trigger the screen bric^tening. Calling 
CursorLocation or SetFadeOelay also indicates user activity. 

F.4 The Speaker 

Function Volume: SpeakeiVolume; 

Pnx»dure SetVolume (volume: SpeakeiVolume); 

Procedure Noise (waveLength: MicioSecondsjt 

Pnicedure Silence; 

Procedure Beep (waveLength: Microseconds; duration: Milliseconds); 

The routines in this section provide square wave output from the Lisa speaker. 
The speaker volume can be set to values in the range (soft) to 7 (loud). 
Volume reads the volume setting; SetVolume sets it The initial volume 
setting is 4. 

Noise produces a sc^re wave of approximately the specified wavelength. 
Silence shuts off the square wave. The minimum wavelength is about 8 
microseconds, which corresponds to a frequency of 125,000 cycles per second, 
well above the audible range. The maximum wavelength is 8,191 micro- 
seconds, which corresporefc to about 122 cycles per second. 

Noise and Silence are called in pairs to start areJ stop square wave output In 
contrast. Beep starts scpjare wave output which will automatically stop after 
the specified period of time. The effects of Noise, Silence and Beep are 
overridden by subsequent calls. 

F.5 The Keytxiard 

The routines in this section provide an interface to the keyboard, the keypad, 
the mouse button and plug, the diskette buttons ard insertion switches, and 
the power switch. Two interfaces are provicted, a |X)llable keyboard state and 
a queue of keyboard events. 

Three physical keyboard layouts are defined, the "Old US Layout" (with 73 
keys on the main keyboard and numeric keypad), the "Final US Layout" (76 
keys) and the "European Layout" (77 keys). Each key has been assigned a 
keycocf^ which uniquely identifies the key. Keycode values range from to 
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127. Table F-1 defines the keycodes for the "Final US Layout", using the 
legends from the US Keytward. The "Old US Layout" has three less keys; |V 
Alpha Enter, and Right Option are not on the old keyboard. The "European 
Layout" has one additional key, ><, with a keycode of $43. 

Tvtrtj keys on the "Old US Layout" gererate keycottes different from the 
corresponding keys on the "Final US Layout". To aid in compatibility, 
software changes the keycode for ~ ' from $7C lo $68, and the keytiide for 
Right QpUon from $68 lo $aE. 

Table F-i 
Keycodes for Tinal US Layout" 



HIGH-^ 


000 



001 
1 


010 
2 


on 


100 
4 


101 

5 


110 
6 


111 

7 


QQOQ 







CLE<« 




— 


( 
9 


E 


A 


0001 
1 


DISK 1 
INSERTED 




- 




+ 


) 



6 


9 

2 


QQIQ 
2 


DISK 1 
BUTTON 




^1 




1 

\ 


U 


7 


3 


0011 
3 


DISK 2 
INSERTED 










I 


8 


$ 
4 


0100 


DISK 2 
BUTTON 


L 
r 


7 




P 


3 


% 
5 


1 


0101 
5 


PARALLEL 
PORT 


L 


8 




BACKSPACE 


K 


R 





0110 
6 


HOUSE 
BUTTON 




9 




ALPHA 
ENTER 


< 
[ 


T 


s 


0111 
7 


HOUSE 
PLUG 




rii 






> 
] 


Y 


w 


1000 
8 


POUER 
BUTTON 




4 


; 


RETURN 


M 


~ 


TAB 


1001 
9 




: 


5 


: 





L 


F 


z 


1010 
A 






6 


: 


■ 


r 


G 


X 


1011 
B 






m 


, 




" 


H 


D 


1100 
C 




: 


' 


: 


7 
/ 


SPACE 


V 


LEFT 
OPTION 


1101 
D 




; 


2 


; 


1 


< 


C 


CAPS 
LOCK 


1110 
E 




: 


3 


: 


RIGHT 
OPTION 


> 


B 


SHIFT 


1111 

F 




: 


NUHERIC 
ENTER 


: 


■ 





N 


« 
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F3.1 Keyboard IdenUflcaUon 

Function Keytxiard: Keytxflci; 

Function Legends: Keytxfld; 

Procedure SetLegends 0d: Keybdici); 

Lisa software supports a host of different keyboards. Eacn keyboard has three 
major attributes: manufacturer^ physical layout, and legends. The chart 
below describes how these three attributes are combined to form a keyboard 
identi- fication number. The keyboards self identify when the machine is 
turned on and when a new keyboard Is attached. Keyboard returns the 
identification number of Uie keyboard currently attached. Legends and 
SetLegends provide a means of pretending to have different legends^ without 
physically replacing the keyboard. 

Keyboard identification numbers: 

7 b b ^.3 2 1 

I Manufacturer I Layout I Legends I 



Manufacturer: 


00 — 


APD (I.e., TKC) 


01 — 




10 -- 

1 aum it> 


Keytronics 


i_ciyuiJi- 

00 ~ 


Old us (73 keys) 


01 -- 




10 — 


European (77 keys) 


11 — 

1 oum it /I or 


Final US (76 keys) 


1-aytHJl/L.ct 

$0F ~ 


Old us 


$26 ~ 


Swiss-German 


$27 — 


Swiss-French 


$29 ~ 


Portuguese 


$29 ~ 


Spanish-Latin American 


$2A ~ 


Danish 


$2B ~ 


Swedish 


$2C ~ 


Italian 


$2D ~ 


French 


$2E ~ 


German 


$2F ~ 


UK 



(allocated for proposed software) 
(allocated for proposed software) 
(allocated for proposed software) 
(allocated for proposed software) 
(allocated for proposed software) 
(hardware not yet available) 
(hardware not yet available) 
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$3C — APL (allocated for proposed software) 

$3D — French-Canadian (allocated for proposed software) 

$3E — US-Dvorak (allocated for proposed software) 

$3F — Final us 

F.5^ Keyboard stale 

Function KeylsDown (key: KeyCap> Boolean; 

Procedure KeyMap (var keys: KeyCapSet); 

Low level access to the keyboard is provided through a pollable keyboard 
state. This state information is based on the physical keycodes defined above. 
KeylsDown returns the position of a single specified key. KeyMap returns a 
128-bit map^ one bit for each key. A zero indicates the key is up^ a one 
indicates down. For the mouse plug^ a zero indicates unplugged^ a one indi- 
cates plugged in. Certain keys are not pollable; the corresponding bits will 
always be zero. These keys are the diskette insertion switches and buttons^ 
parallel port, and power switch. (The parallel port and mouse plug keys are 
unreliable across reboots on older hardware.) 

F.5.3 Keyboard Events 

The hardware interface provides a queue of keyboard events. The events in 
the input queue are generally key down transitions. Each event contains the 
following information: 

keycode ~ physical key 

ascll ~ ASCII interpretation of this key 

state ~ caps-lock, shift, option, «, mouse button and repeat 

mousex ~ x-coordinate of the mouse when the key was pressed 

mouseY ~ Y-coordinate of the mouse when the key was pressed 

time ~ value of the millisecond timer when the key was pressed 

Keycode ~ Keycodes are defined in Table F-l, above. 

Ascii — The ASCII interpretation of keys depends on the state of the caps- 
lock, shift and option keys. Six interpretations are associated with each 
different keyboard layout: 

normal 

caps-lock 

shift or both shift and caps-lock 

option 

option with caps-lock 

option with shift or both shift and caps-lock 
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In most cases the ASCII value returned is obvious. The table below lists the 
cases that aren't so obvious. 

Disk 1 Inserted 

Disk 1 Button 

Disk 2 Inserted 

Disk 1 Button 

Power ButtCHi 

Mouse Button (down) 

Mouse Plug (inj 

Mouse Button (up) 

Mouse Plug (out) 

Enter 

Backspace 

Tab 

Return 

Clear 

$1C (FS) Left 
$1D (GS) Right 

Up 

Down 

Sp«:e 

State ~ A 16-bit word is used to return the state of several keys with each 
event Each bit represents one or more keys; a zero indicates that all of the 
keys are up, a one indicates that at least one of the keys is dowa An 
additional bit indicates, if it is a one, that the event was generated by 
repeating the previous event The following bits of state are currently 
assigned: 





bit 0: 


caps-lock 


bit 1: 


left or right shift 


bit 2: 


left or right option 


bit 3: 


* key 


bit 4: 


mouse button 


bit 5: 


this event is a repeat 



Certain keys never generate events. These keys are caps-lock, both shift 
keys, option keys, and the il key. The mouse button generates events on both 
the down and up transitions. Down transitions have an ascii value of 0, up 
transitions 1. The mouse plug also generates two different events. When the 
mouse is plugged in an event with an ascii value of is returned, when it is 
uiplugged a value of 1 is returned. 
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Function Keytxfeek (repeats: Boolean; inde)c KeytxlQIndex; var event: 
KeyEvent): Boolean; 

KeytNJPeek is used to examine events in the keyboard qi^ue^ without removing 
them from the queue. The first input parameter indicates whether r^Deats are 
desired. The second paraneter is the cpjeue index. The first output para- 
meter indicates whether the sf«cified c^ieue entry contains an event To 
examire ai entire queie, fint call KeytxPeek with a queue index of 1. If ai 
event is relumed, call it again with a c^ue index of 2, etc. 

Function Keyt)dEvent (repeats: Boolean; wait- Boolean; var event KeyEvent> 
Boolearv 

KeybdEvent is used both to determine if a keyboard event is avail^le, and to 
return the event if one is available. The event is removed from the queue. 
KeybdEvent returns a boolean result which is true if en event is returned. 
The first parameter to KeybdEvent is used to indicate if the caller will 
accept repeated events on this call. The second parameter indicates if the 
functiwis shtMJld wait for ai event if one is not immediately available. 

F5.4 Dead Key Diacriticals 

Many languages employ diacritical marks on certain letters. Several of the 
required diacritical mark-letter combinations appear on European keyboards^ 
but otf^rs (to TOt The combinations shown in the table below may be typed as 
a two-key sequeixe^ by first typing the dead key diacritical (which has no 
immediate effect), and then typing the letter. Dead key diacriticals appear on 
keyboard legends as the diacritical mark over a dotted square or hollow box. 



circumflex * ~ a 


e i 6 


grave accent * ~ a 


e i 6 


tilde T "" 3 


ff\ 5 


acute aonent ' ~ a 


&C. i 6 


umlaut " ~ aA 


e T oO uU 



A dead key diacritical followed by a letter which appean in the table above 
yields tl^ corresponding character. The event that is generated contains the 
keycode, state, mouse location and time that correspond to the letter, but the 
ASCII value of the letter-diacritical cofT*)ination. A ctead key diacritical 
followed by a space yields just the diacritical mark. The event contains the 
keycode, state, mouse location and time corresponding to the space, but the 
ASCII value of the diacritical mark. Finally, a dead key diacritical followed 
by any other character (i.e., not a space or defined letter) yields the diacrit- 
ical mark followed by the other character. 

diacritical, defined letter ~> foreign character 

diacritical, space —> diacritical 

discritical, other character ~> diacritical, other character 
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F33 Repeats 

Most keys^ if held down for an extended period of time, may generate 
multiple events (repeats)L The keys that are not repeatable are caps-lock, 
both shifts, both options, the # key, the diskette insertion switches and 
diskette buttons, parallel port, the mouse button and plug, and the power 
buttoa Several conditions must be satisfied before a repeat is generated. 
These conditions are as follows: 

1. KeybdPeek or KeybdEvent is called with repeatsOesired true. 

2. The keyboard event queue is empty. 

3. The key returned in the last event is still down. 

4. No down transitions have occuned since the last event 

5. The key is repeatable. 

6. Enough time has elapsed. 

Repeats generate events with the following attributes: 

keycode ~ original keycode 

ascii — original ASCII interpretation 

state ~ original position of the caps-lock, shift, etc. 

mouseX — revised X-coordinate of the mouse 

mouseY ~ revised Y-coordinate of the mojse 

time ~ revised value of ttre millisecond timer 

Procedure RepeatRate (var initial: Milliseconds; var subsequent: Milliseconds); 

Procedure SetRepeatRate (irutiaL- MilUSeconds; subsequent: Milliseconds); 

The repeat rates can be read and set by calls to RepeatRate and 
SetRepeatRate. "Vnss. rates include an initial delay, which occurs prior to the 
fint repetition, and a subsequent delay, prior to additional repetitions. They 
are both in units of milliseconds. The default repeat rates are 4D0 
milliseconds initially and 100 milliseconds subsequently. 

VJa The Microsecond Timer 

Function MicroTimen Microseconds; 

The MicroTimer function simulates a continuously running 32-bit counter 
which is incremented every microsecond. The timer is reset to each time 
the machine is berated. The timer changes sign abojt once every 35 minutes, 
and rolls over about every 70 minutes. 

The microsecond timer is desig^d for performance measurements. It has a 
resolution of 2 microseconds. Calling MicroTimer from Pascal takes atxxjt 135 
microseconds. Note that interrupt processing will have a major effect on 
microsecond timings. 
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FJ The MillisecontJ Timer 

FunctiGn Timer: Milliseconds; 

The Timer function simulates a continuously running 32-bit counter which is 
incremented every millisecond. The timer is reset to each time the 
machine is txx)ted. The timer cdianges sign dxxjt once every 25 days, and 
rolls over about every 7 weeks. 

The millisecond timer is designed for timing user interactions such as mouse 
clicks ard repeat keys. It can also be used for performaice measurements^ 
assuming that millisecond resolution is sufficient 

F.8 Date and Time 

Procedure DateTime (var date: OateArray); 

Piocedure SetOateTlme (date: DateArray); 

Procedure OateToTime (date: DateArray; var time: Seconds); 

The current date and time are available as a set of 16-bit integers which 
represent the year, day, hour, minute and second, by calling DateTime and 
SetDateTime. The date and time are based on the hardware clock/calendar. 
This restricts dates to the years 1980-1995. The clock/calendar continues to 
operate during soft power off, aid for brief periods on battery backup if the 
machine is unplugged. If the clock/calendar hasn't been set since the last loss 
of battery power, the date and time will be midnight prior to JsHiuary 1, 1980. 
Setting the date and time also sets the time stamp described below. 
DateToTime converts a date and time to a time stan^, defined in the next 
section. 

F.9 Time Stamp 

Function TimeStamp: Seconds; 

Procedure SetTimeStamp (time: Seconds); 

Procedure TimeToDate (time: Seconds; var date: DateArray); 

The current date and time are also available as a 32-bit unsigned integer 
which represents the number of seconds since the midnight prior to 1 January 
1901, by calling TimeStamp and SetTimeStampi The time stamp will roll over 
once every 135 years. Beware—for dates beyond the mid 1960's, the sign bit 
is set The time stamp is based on the hardware clock/calerKlar. This clock 
continues to qoerate charing soft |X)wer off, aid for brief periods on battery 
backup if the machine is unplugged. If the clock/calendar hasn't been set 
since the last loss of battery power, the date and time will be midnight prior 
to January 1, 1980. Setting the time stamp also sets the date and time 
described above. Since the date and time is restricted to 1980-1995, the time 
stamp is also restricted to this rar^. TimeToDate converts a tin« starrp to 
the date etkI time format def ir«d above. 
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F.IO Interface of the Hardware Uhit 

Unit Hardi^are; 
Interface 



type 



Pixels 

ManyPixels 

CursorHeight 

CursorPtr 

OateArray 



Frames 

Seconds 

Milliseconds 

Microseconds 

SpeakerVolume 

ScreenContrast 

KeybdQIndex 

Keybdid 

Keycap 

KeyCapSet 

KeyEvent 



{ Mouse } 



= Integer; 
= Langint; 
= Integer; 
= "Integer; 
= Record 

year: Integer; 

day: Integer; 

hour: Integer; 

minute: Integer; 

second: Integer; 

end; 
» Longint; 
= LongInt; 
= LongInt; 
= LongInt; 
- Integer; 
= Integer; 
= 1..1000; 
= Integer; 

= 0..127; 

= Set of Keycap; 

= Packed Record 

key: Keycap; 

ascii: Char; 

state: Integer; 

mouseX: Pixels; 

mouseY: Pixels; 

time: Milliseconds; 

end; 



Procedure MouseLocation (var x: Pixels; var y: Pixels); 
Procedure MouseUfxiates (delay: Milliseconds); 
Procedure MouseScaling (scale: Boolean); 
Procedure MouseThresh (threshold: Pixels); 
Function MouseOckMieter: ManyPixels; 
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{ Cursor } 

Procedure CursorLocation (x: Pixels; y: Pixels); 
Procedure Cursor Tracking (track: Boolean); 
Procedure Cursorlmage (hotX: Pixels; hotY: Pixels; height; 
Cursorhtei^t; data: CursorPtr; mask: CursorPtr); 

Procedure Busylmage (hotX: Pixels; hotY: Pixels; height: 

CursorHeight; data: CursorPtr; mask: CursorPtr); 
Proceckjre BusyDelay (delay: Milliseconds); 



{ Screen } 

Functim FraneCounter : Frames; 

Procedure ScreenSize (var x: Pixels; var y: Pixels); 

Function Contrast: ScreenContrast; 

Procedure SetContrast (contrast: ScreenContrast); 

Procedure RampContrast (contrast: ScreenContrast); 

Function DimContrast: ScreenContrast; 

Procedure SetDimContrast (contrast: ScreenContrast); 

Function FadeOelay: Milliseconds; 
Procedure SetFadeOelay (delay: Milliseconds); 



{ Speaker } 

Function Volume: SpeakerVolume; 

Procedure SetVolume (volume: SpeakerVolume); 

Procedure Noise (wavelength: Microseconds); 

Procedure Silence; 

Procedure Beep (wavelength: Microseconds; duration: Milliseconds); 
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{ Keyboard > 

Function Keyboard: Keybdid; 

Fmction Legends: Keybdid; 

Procedure SetLegends (id: Keybdid); 

Function KeylsOown (key: KeyCap): Boolean; 

Procedure KeyMap (var keys: KeyCapSet); 

Function KeybdPeek (repeats: Boolean; index: KeybdQIndex; var 

event: KeyEvent): Boolean; 
Function KeybdEvent (repeats: Boolean; wait: Boolean; var event: 

KeyEvent): Boolean; 
Procedure RepeatRate (var initial: Milliseconds; var subsequent: 

Milliseconds); 
Procedure SetRepeatRate (initial: Milliseconds; subsequent: 

Milliseconds); 



{ Timers } 

FtffTCtion MicroTimer: Microseconds; 
Function Timer: Milliseconds; 



{ Date and Time } 

Procedure OateTime (var date: OateArray); 

Procedure SetDateTime (date: DateArray); 

Procedure DateToTime (date: DateArray; var time: SecorMls); 



{ Time Stanp } 

Function TimeStamp: Seconds; 

Procedure SetTimeStarap (time: Seconds); 

Procedure TimeToOate (time: Seconds; var date: DateArray); 
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1 


2 


3 


4 


5 


6 


7 


8 


9 


A 


B 


c 


D 


E 


F 





NUL 


OLE 


SP 





@ 


P 


« 


P 


A 


k 


t 


00 


■ 

6 


- 




:•:•:•:•:•:•; 


1 


SON 


DC1 


! 


1 


A 


Q 


a 


q 


A 


e 


o 


± 


i 


— 




•:•:•:'•:•:•:• 


7 


STX 


0C2 


II 


2 


B 


R 


b 


r 


C 

> 


f 





i 


-■ 


ta 




WM 




.'.•.•.*.'.•.• 


■.•.•.•.:•.•. 


3 


CTX 


DC3 


# 


3 


C 


S 


c 


s 


E 


1 


£ 


2 


/ 


ti 




m 




EOT 


DC4 


$ 


4 


D 


T 


d 


t 


IQ 


1 


§ 


¥ 


f 


1 


:•:•:•;•:•!•: 




4 




'■HM 




ENQ 


NAK 


% 


5 


E 


U 


e 


u 


• ■ 

o 


■ • 

1 


• 


U 


Sl$ 


1 




;.;.;.;.;.;.; 


5 




W&: 


6 


AGK 


SYN 


& 


6 


F 


V 


f 


V 


u 


fi 


If 


d 


A 


• 




W^ 




*.*.*.*.*.*-*. 


'.'.:'.*.'.' 




DEL 


ETD 


1 


7 


G 


w 


g 


w 


d 


6 


B 


Z 


« 







:•:•:•:•:•:•:• 


7 




WM 




BS 


CAN 


( 


8 


H 


X 


h 


X 


a 


6 


® 


TT 


» 


• ■ 

y 




r.W'.w 


8 




WM 


9 


HT 


EH 


) 


9 


1 


Y 


i 


y 


S 


6 


© 


TT 


■ • • 






/*'!*!•/*'! 


A 


LF 


SUB 


« 


. 


J 


z 


• 

J 


z 


■ ■ 

a 


• • 




TM 


i 


i— > 


Wy^. 






B 


VT 


ESC 


+ 


1 


K 


[ 


k 


( 


a 


6 


' 


§ 


A 


•:•:•:•:•:■:•: 




Wy& 


C 


FP 


F$ 


# 


< 


L 


\ 


1 


1 


o 

a 


u 


> • 


Q 


A 


;■.■•;•.■■.■•;•.■• 




WM 


D 


CR 


6S 


— 


= 


M 


] 


m 


} 


P 


Ci 


5li 


n 


6 


WM 




•:•:•:•:•:•:• 






;•:•:•:•:•:•:• 




SO 


RS 


a 


> 


N 


" 


n 


" 


e 


u 


/E 


se 


CE 






:r>:-:v: 


E 






■■.•:•■.•:•:•:•: 


F 


SI 


US 


/ 


? 







o 


DEL 


§ 


• ■ 

u 








oe 


■:•:•:■:■•:•:•: 




S::>:S 




•^^^ 







The first 32 characters and DEL are nonprinting control codes. 
The shaded area is reserved for future use. 
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Appendix H 
Error Messages 



H.1 Error Reporting H-1 

H.2 Lexical Errors ...H-l 

K.3 Syntactic Errors H-2 

H.4 Semaniic Errors H-2 

H.5 Conditional Compilation H-5 

H.6 Compiler Specific Limitations H-5 

H.7 I/O Errors H-5 

H.8 Clascal Errors H-5 

H-9 Code Ger*eration Errors H-6 

H.10 Verification Errors H-6 



Error Messages 



H.1 Error Reporting 

Error reports show the entire line containing an error. Error lines displayed 
on the screen and written to the error listing file ($E Compiler command) 
usually show the line preceding the error for context, too, although there are 
some circumstances in which that line is not shown. 

12 Read(ftrgLffnent) 

13 IF (IOResut<=0) AND (ftxg>=0) THEN 

? 

*** Error 36 *** '; ' expected. 

? 

? 
*** Error 102 *** Identifier not declared. 
*** File example/errors. TEXT *** 

Errors for any one line are accumulated (up to a maximum of 10) and 
reported after the line is fully scanned. Both the error number and its 
associated text are shown along with a "?" pointer to the error's approximate 
location. The pointer usually points to the last character of the token that 
was being processed when the error occuired. The pointer for an error 
message is shown on the line before the message. There may be multiple 
pointers associated with a single message^ or multiple messages associated 
with a single pointer. The source line is shown only once. The line number 
preceding it is the line position within the file whose name is shown as the 
last line in the error report. That line number may be used in conjunction 
with the Editor's "Goto line #" feature to quickly find the errors in the 
specified file. 

HI.2 Lexiceil Enrcrs 

10 Too many digits 

11 Digit expected after '.'in real 

12 Integer overflow 

13 Digit expected in exponent 

14 End of line encountered in string constant 

15 Illegal character in input 

16 Premature end of file in source program 

17 Extra characters encountered after end of progrsm 

18 End of file encountered in a comment 
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H.3 



Syntactic Errors 

20 Illegal symbol 

Error in simple type 
Error in declaration part 
Error in paratieter list 
EiTor in constant 
Error in type 
Error in field list 
Error in factor 
Error in variable 
Identifier expected 
Integer expected 



21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 



' expected 
3' expected 
[' expected 
3' expected 
: ' expected 
; ' expected 
=' expected 
, ' expected 
*' expected 
:=' expected 
program' expected 
of expected 
begin' expected 
end' expected 
then' expected 
until' expected 
do' expected 

to' or 'downto' expected 
file' expected 
if expected 
. ' expected 

implementation' expected 
interface' expected 
intrinsic' expected 
shared' expected 

'.' or '(' is expected following a type-id 



H.4 Semantic Errcnrs 

100 Identifier declared twice 

101 Identifier not of the appropriate class 

102 Identifier not declared 

103 Sign not allowed 

104 Number expected 

105 Loswer bound exceeds upper bound 

106 InccHiopatible subrange types 
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107 Type of constant must be integer 

108 Type must not be real 

109 Tagfield must be scalar or subrange 

110 Type incompatible with with tagfield type 

111 Index type must not be real 

112 Index type must be scalar or subrange 

113 Index type must not be integer or longint 

114 Unsatisfied forward reference for type identifier: 

115 Illegal use of forward reference type identifier 

116 Parameter list is inconsistent with original specification 

117 Function result type is inconsistent with original 
specification 

118 Function result type must be scalar, subrange, or pointer 

119 File value paremeter not allowed 

120 Missing result type in function declaration 

121 F-format for real only 

122 Error in type of standard function parameter 

123 Error in type of standard procedure parameter 

124 Number of parameters does not agree with declaration 

125 Illegal parameter substitution 

126 Result type of pararaeteric function does not agree with 
declaration 

127 Expression is not of set type 

128 Only tests on equality allwed 

129 Strict inclusion not alleged 

130 File comparison not allowed 

131 Illegal type of operand(s) 

132 Type of operand must be boolean 

133 Set element type must be scalar or subrange 

134 Set element types not compatible 

135 Type of variable is not array or string 

136 Index type is not compatible with declaration 

137 Type of variable is not record 

138 Type of variable must be file or pointer 

139 Illegal type of loop control variable 

140 Illegal type of expression 

141 Assignment of files not alloi'^ed 

142 Label type incompatible with selecting expression 

143 Subrange bounds must be scalar 

144 Type conflict of operands 

145 Assignment to standard function is not allowed 

146 Assigmient to formal function is not alleged 

147 No such field in this record 

148 Type error in read 

149 Actual parameter must be a variable 

150 Multi defined case label 

151 Missing corresponding vaoriant declaration 
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152 Real or string tagfields not allowed 

153 Previous declaration was not forward 

154 Substitution of standard procedure or function is not 
allowed 

155 Multidefined label 

156 Multideclared label 

157 Undefined label: 

158 Undeclared label 

159 Value parameter expected 

160 Multidefined record variant 

161 File not allowed here 

162 Unknown compiler directive (not 'external', 'forward', 
'inline', or 'c') 

163 Variable cannot be packed field 

164 Set of real is not allowed 

165 Fields of packed records cannot be var parameters 

166 Case selector expression must be scalar or subrange 

167 String sizes must be equal 

168 String too long 

169 Value out of range 

170 Address of standard procedure cannot be taken 

171 Assignment to function result must be done inside function 

172 Loop control variable must be local 

173 Label value must be in 0..9999 

174 Must exit to an enclosing procedure 

175 Procedure or function has already been declared once 

176 Unsatisfied forward declaration for Procedure 

177 Unsatisfied forward declaration for Function 

178 Type conversion to a different size type is not alleged 

179 Illegal type of operands in constant expression 

180 Division by 

181 NIL is not allowed in a constant expression 

182 i is not allowed in a constant expression 

183 Only certain pre-defined functions ere alleged here 

184 Dereferencing is not allowed here 

185 INLirc code constants must be single word integers 

186 INLINE not allowed because procedure/function is already 
declared 

190 No such unit in this file 
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H.5 Conditional Conpilation 

260 Nevv ccffnpile-time variable must be declared at global level 

261 Undefined cornpile-time variable 

262 Error in compile-tirne expression 

263 Conditional compilation options nested too deeplv 

264 Unmatched ELSEC 

265 Unmatched ENDC 

266 Error in SETC 

267 Unterminated conditional compilation option 

H.6 Conpiler Specific Limitf^ions 

300 Too many nested record scopes 

301 Set limits out of range 

302 String limits out of range 

303 Too many nested procedures/functions 

304 Too many nested include/uses files 

305 Includes not allowed in interface section 
5D6 Pack and unpack are not implemented 

307 Too many units 

308 Set constant out of range 

309 Structure too large ( > 32K ) 

310 Parameter list too large ( >= 32K ) 

312 Size of local data is too large ( > 32K ) 

313 Size of global data is too large ( > 32K ) 

350 Procedure too large 

351 File name in option too long 

352 Too many errors on this line 

H.7 I/O EiTors 

400 Not enough room for code file 

401 Error in rereading code file 

402 Error in reopening text file 

403 Unable to open uses file 

404 Error in reading uses file 

405 Error in opening include file - compilation terminated 

406 Error in rereading pre"</iously read text block 

407 Not enough room for I-code file 

408 Error in writing code file 

409 Error in reading I-code file 

410 Unable to open listing file 
420 I/D error on debug file 

H.8 Clascal Errors 

800 OF missing 

801 Superclass identifier missing 

802 Method NEW is not declared 

803 Subclass declaration not allowed here 

804 Method is not a procedure 
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805 Unimplemented method: 

^6 Unimplemented class: 

807 Superclass identifier is not a class 

808 Identifier is not a class 

809 'NEW not allowed here 

810 'NEW' was expected here 

811 Illegal 'NEW method 

812 Illegal use of class identifier 

813 Unsafe use of a handle in an assigment statement 

814 Unsafe use of a handle in a WITH statement 

815 Unsafe use of a handle as a var parafoeter 

817 Cwnpiler error!!! 

818 Override of non-existent procedure or function 

819 ThisClass function is only legal in methods 

H.9 Code Generation Errors 

1000-1999 Internal code generation errors 

2000 End of I-code file not found 

2CK)1 Expression too complicated, code generator ran out of 

registers 
2002 Code generator tried to free a register that was already 

free 
2003-2005 Error in generating address 
2006-2010 Error In expressions 

2011 Too many global s 

2012 Too many locals 

H.10 Verification Brors 

4000 Bad verification block format 

4001 Source code version conflict 

4002 Compiler version conflict 

4003 Linker version conflict 

4100 Version in file less than minimum version supported by 
program 

4101 Version in file greater than maximum version supported by 
program 
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This appendix lists the files provided on the Pascal 3.0 micro diskettes, first 
alphabetically, then by diskette. 



File Name 

Alert 

apin/syslib.obj 
ftrchiver.Obj 
Assembler. Ob j 
ByteDiff .Obj 
ChangeSeg .Obj 
CharCount .Obj 
Code. Obj 

CodeSize.Obj 
Camp. Text 
Canpare .Help .Text 
Ccmpare.Obj 
Concat .Obj 
Copy .Obj 
Diff.Obj 
DumpObj -Obj 
DumpPatch.Obj 
Edit. Menus. Text 
Editor .Obj 
ErrTool .Obj 
FileDiv.Obj 
FileJoin.Obj 
Find. Obj 
FindlD.Obj 



Pascal 






Diskette Notes Description 


9 


E 


OuickPort support file 




1 


ft Intrinsic unit-misc. 


7 




Utility progran 


5 


C 


Workshop program-SSOOO Assembler 


7 




Utility program 


7 




Utility progrern 


7 




Utility program 


5 


C 


Workshop program-Pascal Code 
Generator 


7 




Utility prograffi 


7 




Utility program 


7 




Support file-Compere 


7 




Utility program 


7 




Utility program 


7 




Utility program 


7 




Utility program 


7 




Utility program 


7 




Utility progra-ft 


5 


C 


Support file-Editor menus file 


5 


C 


Workshop program-Editor 


7 




Utility program 


7 




Utility program 


7 




Utility program 


7 




Utility program 


7 




Utility program 



Note 
Note 

Note 



Note 
Note 
Note 
Note 



A: These files are used for the installation procedure but are not installed. 
B: These files are the minimum necessary to run a user program in the 

Workshop erivironment. A user program may require other files as well. 
C: These files are necessary for running the minimum Pascal Workshop 

(Editor, Assembler, Pascal Compiler afid Code Generator, Linker, and 

Debugger). 
D: These files are needed only for developing Macintosh software. 
E: These files are needed only for developing Lisa QuickPort software. 
F: These file-s are needed only by the Lisa Office System. 
G: These files are needed only for developing Lisa QuickDraw software. 
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File Name 

FincMord.Obj 

font . heur 

font . heur 

font. lib 

font. lib 

gxref .Obj 

InstallTool.Obj 

installwsplirase 

Intrinsic. Lib 

Intrinsic. Lib 

lOSFPLIB.Obj 

iospaslib.obj 

iospaslib.obj 

lUManager.Obj 

LIBTK/PftBC.TEXT 

LineCount.Obj 

Linker .Obj 

LlCcount .Obj 

MAC/Mac.Boot 

lifC/MacCom.Obj 

liftC/RMaker.Obj 

N68K .ERR 

N68K. OPCODES 

ObjIOLib.Obj 

CEMsyscall.Obj 

O^rrs.Err 

paper. text 

Pascal .Obj 

PasErrs.Err 

PasLibCall.Obj 

PasMat. Help. Text 

PasMat.Obj 

PortConfig.Obj 

PRLib.Obj 



Pascal 




Diskette 


Not( 


7 




1 


ft 


2 


C 


1 


A 


2 


C 


7 




8 


E 


1 


ft 


1 


A 


2 


BC 


6 


C 


1 


ft 


2 


BC 


3 




9 


E 


7 




6 


C 


7 




9 


D 


9 


D 


9 


D 


5 


C 


5 


C 


4 


C 


6 




5 


C 


5 


C 


5 


C 


5 


C 


6 




7 




7 




4 




6 


F 



Description 

Utility program 

Support file 

Support file 

Support file-tiny font library 

Support file-font library 

Utility program 

Utility program 

Support file 

Library directory-intrinsic units 

Library directory-intrinsic units 

Intrinsic unit-floating point 

Intrinsic unit-Pascal support 

Intrinsic unit-Pascal support 

Utility program 

OuickPort support file 

Utility program 

Workshop program-Linker 

Utility program 

Support file-Mac boot code 

Utility program 

Utility program 

Support file-ftsserftbler 

Support file-Assembler 

Intrinsic unit-object files 

Regular unit-privileged system calls 

Support file-error message text 

Support file-Editor stationery 

Workshop program-Pascal Compiler 

Support file-error message text 

Intrinsic unit-Pascal support 

Support file-Pasmat 

Utility program 

Utility program 

Intrinsic unit-Printing 



Note A: These files are used for the installation procedure btJt are not installed. 
Note B: These files are the minimum necessary to run a user program in the 

Workshop environment. A user program mary require other files as well. 
Note C: Thes:e files are necessary for running the minimum Pascal Workshop 

(Editor, Assembler, Pascal Compiler and Code Generator, Linker, and 

Debugger). 
Note D: These files ere needed only for developing Macintosh software. 
Note E: These files are needed only for dev;eloping Lisa QuickPort software. 
Note F: These files are needed only by the Lisa Office System. 
Note G: These files are needed only for de-'yeloping Lisa QuickDraw softM/are. 
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Pascal Workshop Files 



Pascal 
File Nane Diskette 

ProcNernes. Help. Text 7 

ProcNemes.Obj 7 

OD/boxes.Obj 9 

OD/boxes.text 9 

QD/graf3cl.0bj 9 

OD/graf types. text 9 

CJD/Hardwere.Obj 9 

OD/m/boxes.text 9 

CD/m/sample.text 9 

OD/S8n»ple.0bj 9 

(X>/sample.text 9 

IX)/support .Obj 9 

OP/BOXES. LLIST .TEXT 9 

qp/boxes.text 9 

0P/Graf3D.Obj 9 

iP/Hsrdware.Obj 9 

qp/mainbaud.text 9 

OP/Make.Text 9 

qp/mAUD. CONFIG. TEXT 9 

qp/HBftUD.VT 100 .TEXT 9 

qp/mouseinput.text 9 

qp/mousei nput 2 . TEXT 9 

OP/PHRftSE 9 

qp/phuser .text 9 

qp/DDSAMPLE. CONFIG. TEXT 9 

qp/qdsample. pic. TEXT 9 

qp/qdsarnple.text 9 

qp/ubaudr ate. text 9 

QP/UQPortCall .Obj 9 

iPAIOPortGraph.Obj 9 

OPAKPortSoroc.Obj 9 

qp/uqpor t user . TEXT 9 

OP/UOPortVTlOO.Obj 9 

qp/uqpsupport .TEXT 9 



Notes 



Description 

Support file-ProcNwnes 
Utility program 
QuickDraw example program 
QuickDraw example source 
Regular unit-3D graphics 
QuickDraw assembly interfaces 
Regular unit-hardware interfaces 
QuickDraw example exec file 
QuickDraw example exec file 
QuickDraw example program 
QuickDraw example source 
Regular unit-QuickDraw support 
QuickPort sample program 
QuickPort swnple program 
Regular unit-3D graphics 
Regular unit-hardware interface 
QuickPort sample program 
QuickPort exec file 
QuickPort sample program 
QuickPort sample program 
QuickPort sarnple program 
QuickPort sample program 
Support file-OuickPort 
QuickPort sample program 
QuickPort sample program 
QuickPort sample program 
QuickPort sample program 
QuickPort satjple program 
Regular unit-QuickPort interfaces 
Regular unit-QuickPort interfaces 
Regular unit-QuickPort interfaces 
QuickPort sample program 
Regular unit-OuickPort interfaces 
QuickPort support file 



Note A: These files ai"e used for the installation procedure but are not installed. 
Note B: These files are the minimum necessary to run a user program in the 

Workshop erivironment. A user program may require other files: qs well. 
Note C: These files are necessary for running the minimum Pascal Workshop 

(Editor^ Assembler^ Pascal Compiler arid Code Generator^ Linker, and 

Debugger). 
Note D: These files are needed only for developing Macintosh software. 
Note E: These files are needed only for developing Lisa QuickPort software. 
Note F: These f iie^ are needed only by the Lisa Office System. 
Note G: These files are needed only for dev>/eloping Lisa QuickDraw software. 
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Pascal 




File Name 


Diskette 


Not( 


OPAIOuickPort.Obj 


9 


E 


qp/user tab -TEXT 


9 


E 


qp/uuserterm . text 


9 


E 


QPlib.Obj 


9 


E 


qpsernpl e . not e . t ext 


9 


E 


Search. Ob j 


7 




SegMap.Obj 


7 




shell. Workshop 


5 


BC 


Showlnterf ace. Help. Text 


7 




ShowInterface.Obj 


7 




SUlib.Obj 


4 


BC 


SXref . Assembly .Text 


7 




SXref. Basic. Text 


7 




SXref. Ob j 


7 




SXref .Pascal. Text 


7 




SyslLib.Obj 


4 


BC: 


Sys2Lib.0bj 


6 


EF 


SysCall.Obj 


6 




system. bt_Pri8rfl Disk 


1 


C 


systern.bt_Profile 


1 


C 


system. bt_Soniy 


2 


C 


syst em . cdd 


1 


BC 


system. cd_2 Port Card 


1 


C 


syst em. cd_ftr chive Tape 


1 


C 


system.cd_Console 


1 


BC 


systern.cd_Modem ft 


2 


C 


system. cd_P8r all el Cable 


2 


C 


system.cd_Pri8m Card 


1 


C 


system.cd_Priarn Disk 


1 


c 


system . cd_Pr of i 1 e 


1 


BC 



syst em. cd Serial Cable 



Notes Description 

Regular unit-OuickPort interfaces 

OuickPort sample program 

OuickPort sample progrsm 

Intrinsic unit-OuickPort 

OuickPort ssrople progran notes 

Utility program 

Utility program 

Workshop shell 

Support file-ShcwInterface 

Utility program 

Intrinsic unit-standard units 

Support file 

Support file 

Utility program 

Support file 

Intrinsic unit-misc. 

Intrinsic unit-misc. 

Intrinsic unit-OS interfaces 

System support-Prism boot tracks 

System support-ProFile boot tracks 

System support-Sony boot tracks 

System support-configurable driver 

directory 

System support-2-port card driver 

System support-Archive tape driver 

System support-console driver 

SystCTft support-Europe-modem ft driver 

System support-parallel cable driver 

System support-Priern card driver 

System support-Priam disk driver 

System support-ProFile or internal 

hard disk driver 

System support-USA-serial cable 

driver 



C 



Note A: These files are used for the installation procedure btA are not installed. 
Note B: These files are the minimum necessary to run a user program in the 

Workshop environment. A user program may require other files as well. 
Note C: These files: are necess:ary for running the minimum Pascal Workshop 

(Editor, Assembler, Pascal Compiler and Code Generator^ Linker, and 

Debugger). 
Note D: These files are needed only for developing Macintosh software. 
Note E: These files are needed only for developing Lisa QuickPort softv/are. 
Note F: These files are needed only by the Lisa Office System. 
Note G: These files are needed only for developing Lisa QuickDraw software. 
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File Name 

syster(i.cd_Sony 
system. debug 
systeffl.debug2 
system. lid 
system. lid 
system. OS 
system. OS 
SYSTEM. PRD 



l^ascal 
Diskette 

1 
3 
3 
1 
2 
1 
3 
3 



System.PR_Daisy Wheel Printer 3 

system .PR_Imagewr iter / i| DflP 3 

System.PR_Ink Jet Printer 1 

s-j/st em. shell 1 

s\/st em. shell 2 

SYSTEM. mPftCK 1 

TK2LIB.0bj 8 

TKLIB.Obj 8 

Tools. Help. Text 7 

Transfer .Menus. Text 6 

Transfer. Ob j 6 

Translit.Obj 7 

iJXref .Ob j 7 

WordCount.Obj 7 

Workshop. Step. Help. Text 5 

ICIRKSHOPERRS.ERR 5 

xref. help. text 7 

xref.Obj 7 

{T11}BIJTT0NS 3 

[Tiliobj 3 

i'TlUPHRftSE 3 



Notes Description 

BC System support-rnicro diskette driver 
System program-debugger 
System progrem-debugger 
System program-low-level drivers 
System program-low-level drivers 
System program-OS 
System program-OS 
System support-print code 
configuration 

System support-daisy wheel printer 
System support-Imagewriter/Dt'P 
Systerft support-ink jet printer 
Installation shell 
Environments window 
System support-unpack table 
Intrinsic unit-ToolKit 
Intrinsic unit-ToolKit 
Support file-various utilities 
Support file-Transfer menus file 
Workshop progrfffi-Transfer progreffl 
Utility program 
Utility progrwfl 
Utility program 
Support file-Workshop shell 
Support file-error message text 
Support file-XRef 
Utility program 
Support file-Preferences 
Workshop progrsrn-Preferences 
Support file-Preferences 



C 

c 

A 

BC: 

A 



F 

F 

F 

A 

BC 

BC 

E 

E 



Note A: These files are used for the installation procedure but are not Installed. 
Note B: These files are the minimum necessary to run a user program in the 

Workshop environment. A usei* program may require other files as well. 
Note C: These files are necessary for running the minimum Pascal Workshop 

(Editor, Assembler, Pascal Compiler and Code Generator, Linker, and 

Debugger). 
Note D: These files are needed only for developing Macintosh software. 
Note E: These files are needed only for developing Lisa QuickPort software. 
Note F: These files are needed only by the Lisa Office System. 
Note G: These files are needed only for developing Lisa QuickDraw software. 
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Pascal Workshop Files 



Pascal Diskette 1 

Filename 



apin/syslib.obj 

font .heur 

font. lib 

installwsphrase 

Intrinsic. Lib 

iospaslib.obj 

systatJ.bt_Pri8m Disk 

system.bt_Profile 

system. odd 

system. cd_2 Port Card 

system. cd_ftr chive Tape 

system.cd_Console 

system.cd_Pri8m Card 

system.cd_Pri8rft Disk 

systerfi.cd_Profile 

s\/'stem.cd_Sony 

system. lid 

system. OS 

system. shell 

SYSTEM. UNPACK 



Size 


Psize 


89600 


175 


1536 


3 


5746 


12 


17422 


35 


1536 


3 


24576 


48 


11264 


22 


11776 


23 


1536 


3 


1024 


2 


4096 


8 


5120 


10 


2048 


4 


3584 


7 


5632 


11 


3584 


7 


10240 


20 


142848 


279 


16896 


33 


1024 


2 



707 total blocks for files listed 

31 blocks of OS overhead for catalog and files listed 

34 blocks free out of 772 



Pascal Diskette 2 






Filename 


Size 


Psize 


font . heur 


1536 


3 


font. lib 


264070 


516 


Intrinsic. Lib 


5120 


10 


iospaslib.obj 


47616 


93 


system.bt_Sony 


11776 


23 


systera.cdjiodem A 


8192 


16 


system.cd_P8rallel Cable 


2560 


5 


system.cd_Serial Cable 


7168 


14 


system. lid 


10240 


20 


system. shell 


7680 


15 



715 total blocks for files listed 

21 blocks of OS overhead for catalog and files listed 

36 blocks free out of 772 



1-6 



Pa^csl Reference Manual 



Pascal Workshop Files 



Pascal Diskette 3 






Filename 


Size 1 


Psize 


lUManager.Obj 


14336 


28 


system. debug 


32768 


64 


system.clebug2 


16384 


32 


system. OS 


161792 


316 


SYSTEM. PRO 


402 


1 


System.PR_Dalsy Wheel P... 


15872 


31 


system .PR Imagewriter /... 


17408 


34 


{T11}BUTT0NS 


43520 


85 


{Tll}obj 


31232 


61 


{Tll}PHRftSE 


11215 


22 



674 total blocks for files listed 

32 blocks of OS overhead for catalog and files listed 

78 blocks free out of 772 



Pascal Diskette 4 






Filenane 


Size 


Psize 


ObjIOLib.Obj 

PortConfig.Obj 

SUlib.Obj 

SyslLib.Obj 

System .R^_Ink Jet Print... 


59392 

6144 

27648 

275968 

14336 


116 
12 
54 

539 
28 



749 total blocks for files listed 

27 blocks of OS overhead for catalog and files listed 

8 blocks free out of 772 
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Pascal Works^iop Files 



Pascal Diskette 5 






Filename 


Size i 


Psize 


Assembler .Ob j 


42496 


83 


Code. Ob j 


51712 


101 


Edit .Menus. Text 


3072 


6 


Editor. Ob j 


40960 


80 


N68K.ERR 


3072 


6 


N68K. OPCODES 


4096 


8 


OSErrs.Err 


22528 


AA 


paper. text 


2048 


A 


Pascal .Ob j 


116736 


228 


PasErrs.Err 


7680 


15 


shell. Workshop 


76800 


150 


Workshop -Step .Help .Text 


2048 


4 


WORKSHOPERRS.ERR 


2048 


4 



733 total blocks for files listed 

35 blocks of OS overhead for catalog and files listed 

16 blocks free out of 772 



Pascal Diskette 6 






Filename 


Size 


Psize 


lOSFPLIB.Obj 


66048 


129 


Linker. Ob j 


37888 


74 


OEMsyscall-Obj 


4608 


9 


PasLibCall.Obj 


2560 


5 


PRLlb.Obj 


43520 


85 


Sys2Lib.0bj 


134656 


263 


SysCall .Obj 


22016 


43 


Transfer .Menus. Text 


2048 


4 


Transfer .Obj 


14336 


28 



640 total blocks for files listed 

30 blocks of OS overhead for catalog and files listed 

114 blocks free out of 772 
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Pascal Diskette 7 






Filename 


Size i 


=size 


ftrchiver .Obj 


12288 


24 


ByteDiff.Obj 


2560 


5 


ChangeSeg .Obj 


2560 


5 


CharCount .Obj 


5120 


10 


CodeSize.Obj 


8704 


17 


Comp.Text 


2048 


4 


Conpare. Help. Text 


7168 


14 


Ccmpare.Obj 


12800 


25 


Concat .Obj 


5120 


10 


Copy .Obj 


6144 


12 


Diff.Obj 


9216 


18 


DumpObj .Obj 


22016 


43 


DumpPatch.Obj 


8192 


16 


ErrTool .Obj 


3072 


6 


FileDiv.Obj 


4608 


9 


FileJoin.Obj 


3584 


7 


Find. Obj 


8192 


16 


FindlD.Obj 


2560 


5 


FindWord.Obj 


1536 


3 


gxref .Obj 


14848 


29 


LineCount .Obj 


5120 


10 


LWCcount .Obj 


5120 


10 


PasMat. Help. Text 


11264 


22 


PasMat.Obj 


37376 


73 


ProcNarftes .Help .Text 


5120 


10 


ProcNames.Obj 


19968 


39 


Search. Obj 


8192 


16 


SegMap.Obj 


2560 


5 


Showlnterf ace .Help .Text 


4096 


8 


ShowInterface.Obj 


29696 


58 


SXref . Assembly .Text 


3072 


6 


:3?<ref. Basic. Text 


3072 


6 


SXref .Obj 


15360 


30 


SXref .Pascal .Text 


2048 


4 


Tools. Help. Text 


8192 


16 


Translit .Obj 


7168 


14 


UXref-Obj 


14336 


28 


WordCount .Obj 


5120 


10 


xref. help. text 


5120 


10 


xref .Obj 


25600 


50 



703 total blocks for files listed 

70 blocks of OS overhead for catalog and files listed 

11 blocks free out of 772 
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Pascal Diskette 8 

Filename 

InstallTool.Obj 

TK2LIB.0bj 

TKLIB.Obj 



Size Psize 

14336 28 
155136 303 
174592 341 



672 total blocks for files listed 

25 blocks of OS overhead for catalog and files listed 

87 blocks free out of 772 



Pascal Diskette 9 






Filename 


Size 


Psiz 


ALERT 


18432 


36 


LIBTK/^ABC.TEXT 


11264 


22 


hftC/Mac.Boot 


2560 


5 


MftC/MacCom.Obj 


20992 


41 


MAC/RMaker.Obj 


24576 


48 


OD/boxes.Obj 


7680 


15 


OD/boxes.text 


6144 


12 


OD/graf 3d .Obj 


10752 


21 


OD/graf types. text 


14336 


28 


OD/Hardware.Obj 


4608 


9 


OO/ht/boxes.text 


2048 


4 


OD/rn/sQTflple.text 


2048 


4 


OD/sample.Obj 


7680 


15 


OD/sample.text 


12288 


24 


OD/support.Obj 


3072 


6 


OP/BOXES. LLIST. TEXT 


2048 


4 


qp/boxes.text 


6144 


12 


0P/Graf3D.0bj 


10752 


21 


OP/Hardware.Obj 


3584 


7 


qp/mainbaud.text 


2048 


4 


OP/Make.Text 


5120 


10 


qp/tlBftUD. CONFIG. TEXT 


3072 


6 


qp/MBftUD.VT 100. TEXT 


2048 


4 


qp/mouseinput .text 


7168 


14 


qp/mouseinput2 .TEXT 


8192 


16 


OP/PHRftSE 


7288 


15 


qp/phuser.text 


4096 


8 


qp/DDSfWLE .CONFIG .TEXT 


14336 


28 


qp/qdsemple . pic .TEXT 


13312 


26 


qp/qdsarnple.text 


13312 


26 


qp/ubaiudrate . text 


3072 


6 
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OP/UOPortCall.Obj 


6656 


13 


OPAIOPor tGr aph . Ob j 


1536 


3 


OPAKPor tSor oc . Ob j 


1536 


3 


qp/uqportuser .TEXT 


2048 


4 


OPAIOPor tVT 100. Ob j 


1536 


3 


qp/uqpsupport .TEXT 


3072 


6 


OPAIOuickPort .Obj 


1536 


3 


qp/user tab. TEXT 


2048 


4 


qp/uuser term. text 


3072 


6 


OPlib.Obj 


60416 


118 


qpsample. note. text 


3072 


6 



666 total blocks for files listed 

72 blocks of OS overhead for catalog and files listed 

46 blocks free out of 772 
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Appendix J 
Listing Formats 



Six different listing formats can be generated by the Compiler and Code Generator, 
allowing you to show different amounts of generated assembly code and other 
information intermixed with your Pascal source. All the listings show the total line 
number count and the line number within each include file, plus lexical information. 
An example of each of the listing formats is shown at the end of this appendix. 
The Compiler commands and Compiler and Code Generator options that control the 
listing are described in the Release 3.0 Notes to Chapter 12. 

The six different listing formats are: 

1. A ta^i'c listing as produced by the Compiler. The other five listing formats 
are modifications of this basic format-. Unless you specify $L- as an option 
to the Code Generator, you won't see this listing, because its presence is a 
signal to the Code Generator that it should modify the listing to one of the 
other five formats (its name is passed in the I-code). 

In the basic listing, each line of the source is preceded by five fields of 
information: 

Field 1: The total line count. 

Field 2: The current include and uses nesting depth. If the input is not 
from either a uses or include, this field will be blank. 

Field 3: The line number of each line with respect to the include file 

containing that line. All error references are reported in terms of 
this line number. You may use it in conjunction with the Editor's 
"Goto line #" featLffe to easily locate the lines that contain the 
reported errors. 

Field 4: This field consists of two indicators (left and right) that reflect the 
static block nesting level. The left indicator is incremented (mod 
10) and displayed whenever a begin, repeat, or ca^ is encountered. 
On termination of these structures with an end or until, the right 
indicator is displayed and then decremented. It is thus easy to 
match tegin, repeat, and case statements with their matching 
terminations. 
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Field 5: A letter in the this field reflects the static level of procedures amd 
functions. The character is updated for each procedure or function 
nest level ("A" for level 1, "B" for level 2, and so on), and 
displayed on the line containing the heading, and on the begpn and 
Old associated with the procedure or function body. Using this 
field you can easily find the procedure or function body for its 
corresponding heading when there are nested procedures declared 
between the heading and its body. 

Note that if the source being shown in the listing is being skipped due to a 
$IFC Compiler comnnand, the lexical information (fields 4 and 5) is not 
shown. You can then tell from the listing what is being skipped. 

2. A minimum listing containing all the basic listing information plus the 
LisaBug procedure-relative addresss corresponding to the statements. 
Generally, the addresses reflect the start of the associated statements. This 
is the form of listing produced by the Code Generator when $ASM- is in 
effect (either by option or Compiler commands). 

3. A full listing containing the basic listing plus the generated assembly code 
interleaved with the Pascal source. In general, the code generated for a 
statement follows that statement, but there are some conditions which cause 
the code to precede its associated statement. The full listing is produced 
when $ASM4- is in effect (either by option or Compiler commands). 

4. A full listing b^'' f^ocedure containing the basic listing plus the generated 
assembly code on a procedure basis, that is, all the source for a procedure is 
shown before its generated code. This listing is produced when $ASM* is in 
effect and you specify the $ASM PROG option. 

5. An (dissembler input source containing the original Pascal source as 
comments interleaved with the corresponding assembly code. This listing is 
produced when $ASM* is in effect and you specify the $ASM ONLY option. 
There is no guarantee that the source produced is completely valid 
Assembler input (although what is generated will be syntactically correct). 
The Code Generator generates appropriate .DEF and .REF statements and 
labels for branches and data. Procedure references whose names conflict 
with Assembler opcodes and directives are renamed by padding the original 
name with percent characters (e.g., "MOVE" would become "MOWE%%%%'% A 
conflicting name is defined as one that occurs in the Assembler's opcode file 
N68K-OPCODES. (This file is now also used by the Code Generator when the 
$ASM ONLY option is used.) 
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6. An ^^^embler input sotff-ce fy' procedure containing the original Pascal 
source for an entire procedure as comments followed by the corresponding 
assembly code. This listing is produced when SASM-t' is in effect and you 
specify both the Code Generator options $ASM ONLY and $ASM PROC. 

Note that the only way to see the generated code is to use $ASM*, either as an 
option to the Compiler or Code Generator or as Compiler directives. $ASM PRCX; 
causes the display of the code on a procedure basis, and $ASM ONLY causes the 
listing to be produced in Assembler input format. 
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LISTING FCV^AT #1 - Basic listing formd; as prfMiuced by the Corr^iler 

Lisa Pascal Cof^iler V3.22 (i4-Jun-84> 13:31:43 15-Ajn-8a 



1 




1 ~ 


PRUGRAM Exanpie; 


2 




2 ~ 




3 




3 ~ 


VAR 


4 
5 




a ~ 

5 __ 

6 — 


Argument: Longint; 


6 




m Factorial) 


7 




1 — A 


FUHCTIOH Factorial (Arg: Ljonglnt>: Longint; 


8 




2 ~ 




9 




3 0- A 


BEGIN {Factorial} 


10 




4 ~ 


IF Arg<=l THEN 


11 




5 — 


Factorial := l 


12 




6 — 


ELSE 


13 




7 ~ 


Factorial := Arg^FactoriaKArg-1); 


14 




8 -0 A 


END; {Factorial) 


15 




7 ~ 




16 




8 0- 


KGIN {Exanple) 


17 




9 1- 


REPEAT 


18 




10 — 


writein; 


19 




11 — 


Wri tec Enter argunent: '); 


20 




12 ~ 


ReadCArgunent); 


21 




13 ~ 


IF (lOResuIt<=0) AND <Argiment>=0) THEN 


22 




14 — 


«riteLn<'FaDtorial<', Arcpjnent: 1, ') 


23 




15 ~ 


Factorial (Argunent): i>; 


24 




16 -1 


UNTIL Argunent<0; 


25 




17 -0 


zm. {Exar^le) 



Elapsed tine: 1.033 seconds. 

Conpilation conplete - no errors found. 25 lines. 
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LISTING FCM^?MAT #2 - Minimum listing format showing LisaBt^ addresses 



Lisa Pascal conpiler V3.22 (ia-oun-8<EJ) 

Lisa Pascal I1C68000 Code Generator V3.i4 <ifl-0un-8«) 



13:31:43 15-Jun-84 
13:36:41 i5-Jun-8« 



1 

2 
3 




1 ~ 

2 ~ 

3 ~ 


1 


PROGRiW EXSr^le; 






'om 


5 




4 ~ 

5 ~ 

6 ~ 




Argument: Longint-, 


6 






<JI Factorial} 


7 




1 ~ A 




FUNCTIOM Factorial (Arg: Longint): Longint; 


8 




2 ~ 






9 




3 0- A 




BEGIN (Factorial) 


10 




4 ~ 


000008 


IF Arg<=l THEN 


11 




5 ~ 


000012 


Factorial := l 


12 




6 ~ 


OOOOIA 


ELSE 


13 




7 — 


OOOOIA 


Factorial := Aig*Factorial(Ai-g-l); 


14 




8 -0 A 




EHD-, (Factorial) 


15 




7 — 






16 




8 0- 




BEGIN (Exanple) 


17 




9 1- 




REPEAT 


18 




10 ~ 


000016 


tfriteln; 


19 




11 ~ 


(WOOIE 


tfrite< 'Enter argument: '): 


20 




12 — 


00002C 


Read<Argunent); 


21 




13 ~ 


000038 


IF (lOResult<=0) AND (Ai-guMent>=0) THEN 


22 




14 — 


00004A 


tfritelnCFsctorialC, Argunent: 1, ') 


23 




15 ~ 


00004A 


Factorial (Argunent): 1); 


24 




16 -1 


00009C 


UNTIL Argunent<0; 


25 




17 -0 




Eh©. (Exanple) 



Elapsed OTnpilation tine: 1.483 seconds. 
Conpilation couplets - no errors found. 25 lines. 
Elapsed code generator tine: 1.228 secorafe. 
Total c«Je size = 284 
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LISTING FORMAT #3 - Full listing farrrafc with generated code interleaved 



Lisa Psscal conpiler V3.22 (la-Jun-sa) 

Lisa Pascal I1C68000 Code Generator V3.ia (l4-Jun-8fl) 

1 1 ~ PROGRAM Example; 



13:31:43 IS-Jun-Sa 
13:37:09 i5-0un-8fl 



3 




3 ~ 


VAR 






4 
5 

6 




4 — 

5 ~ 

6 ~ 


Argument: Ltwiglnt 


' 






{^1 Factorial} 






7 


1 


1 ~ 


A FUNCTION Factor iaJ(Arg: Longlnt): Longint; 


8 


1 


2 — 








9 


1 


3 0- 


A BEGIN {Factorial} 












OOOOOO 4A6F FOOO FACTORIA TST.W 


|F000(A7) 








000004 4E56 0000 


LINK 


A6,«$0000 


10 


1 


4 ~ 


IF Arg<=l THEN 












000(K)8 OCAE 0000 0001 


CMPI.L 


«|00000001,$0008(A6) 








OOOOOE 0008 












(X»010 6E08 


&3T.S 


uraoi ; OOOOOOIA 


11 


1 


5 — 


Factorial : 


= 1 










(»0012 7001 


MOVEQ 


«|01,D0 








000014 2D40 (WXtt 


HOVE.L 


DO,$0OOC<A6) 








»D0018 601A 


BRA.S 


lJ0a)2 : 00)00034 


12 


1 


6 ~ 


ELSE 






13 


1 


7 ~ 


Factorial :: 


= Arg*Factorial<Ai-g-l); 








OOOOIA 42A7 LOOOl 


CLR.L 


-(A7> 








OOOOIC 202E 0008 


HOVE.L 


?0008<A6),D0 








000)20 5380 


SUBQ.L 


sn.Do 








000022 2F00 


MOVE.L 


D0,-<A7) 








000024 4E&^ 0000 


JSR 


FACTORIA 








000028 2F2E 0008 


MOVE.L 


|0008(A6).-<A7> 








a»02C aEBA (WK) 


JSft 


JKI MULa 








000030 2D5F OOOC 


HOVE.L 


<A7)*,$000C<A6) 








000034 4E5E L0002 


UNLK 


A6 








OC»036 2E9F 


HOVE.L 


(A7)*,(:A7) 








000038 4E75 


RTS 










00003A C641 4354 4F52 


.WORD 


$C641,$4354,$4F52 ; ".ACTOR' 








(X»040 4941 


-VORD 


$4941 ; "lA" 








0OOM2 0000 CstSize 


.WORD 


Laist-CstSize-2 








000044 Last 






14 


1 


8 -0 A END; {Factorial} 






15 




7 ~ 








16 




8 0- 


BEGIN {Example} 






17 




9 1- 


REPEAT 












OOOOOO 4Ea^ 0C»0 Emf\L 


JSR 


X BEGIN 








0O0CK)4 4E56 00C» 


LINK 


A6,S$0000 








000008 2ca= 


MOVE.L 


(A7)*,A6 








OOOOOA 4EIS FFFC 


LINK 


t&.W^^ 








OOCKXME «=H) OttO 


aSA.L 


5(»10<A5),A7 








0(XW12 4EBA QOOQ 


3sa 


XJNIT 


18 




10 ~ 


WriteUi; 












00(Xa6 2F2D OOOC UW02 


MOVE.L 


|000C(A5),-(A7) 








OOOOIA 4EBA 0000 


JSR 


m LN 


19 




11 — 


Vft-i tec 'Enter argunent: 


■)" 








OOOOIE 2Fa) OOOC 


MO'JE.L 


*00OC<A5),-<A7) 








»X)022 487A 0OA2 


PEA 


Cst0003 ; OCK)OOCK» 








000026 4267 


CLR.W 


-(A7) 








000028 4EBA 0000 


J^ 


W STR 


20 




12 ~ 


Read(Argu>ient) 


; 





J-6 



Pssc&l Reference Manual 



Listing Formats 







00002C 2F2D 0008 






MOVE.L 


?<J008(A5),-(A7) 








000030 «EBA 0000 






JSR 


MR I 








00003a 2B9=^ FFFC 






MOVE.L 


(A7)*,$FFFC<A5) 




21 


13 ~ 


IF 


<IOResuIt<=0) AND (Argijnent>=0) TfCN 








000038 aEBA 0000 






JSR 


% lORES 








00003C aA5F 






TST.W 


<A7)* 








00003E 5FC0 






SLE 


DO 








OOOOaO «AAD FFFC 






TST.L 


|FFFC(A5) 








ooooaa 5cci 






SGE 


Di 








000M6 COML 






AND. 8 


D1,D0 








000048 674A 






BEQ.S 


LOOOl : 


o(»ooo9a 


22 


la ~ 




WriteLn( 'Factorial < 


*, Argunent: 1, ■) 


=', 


23 


15 ~ 






Factoniaii<Ai-gunent): i); 








^XfXMfi 2F2D OOOC 






MOVE.L 


«0OOC(A5),-(A7) 








0000«E a87A 006ft 






PEA 


Cst0002 ; 


OOOOOOBA 






0O0OS2 4267 






CIR.W 


-(A7) 








00)054 «EBA 0000 






JSR 


W STR 








000CB8 2F20 OOOC 






WVE.L 


^0OIK<A5>,-<A7) 








OOCKBC 2F2D FFFC 






MOVE.L 


$FFFC(A5>,-(A7) 








CKW080 3F3; 0CM3i 






MiDVE.W 


»|0001,-(A7) 








000064 aEBA 0000 






JSR 


M I 








000068 2F2D OOOC 






MOVE.L 


$0O0C(A5>.-(A7) 








00006C 4S7ft 0048 






PEA 


CStOOOl ; 


OOOOOOK 






000070 4267 






CUR.V 


-(A7) 








(XJOOm aEBA (HXK) 






JSR 


%i STR 








000076 2F2D OOCtt 






MO\€.L 


|050C<A5),-(A7) 








00007A a2A7 






CLR.L 


-(A7) 








00007C 2F20 FFFC 






W)VE.L 


$FFFC<A5).-<A7) 








000080 aEBA 0000 






JSR 


FACTORift 








000084 3F3C 0001 






MOVE.y 


«f0001,-(A7> 








000088 4EBA 0000 






JSR 


m I 








00008C 2F2D OOCTC 






MOVE.L 


$0O0C(A5),-(A7) 








VXXm aEBA (K)00 






JSR 


m LN 








000094 a<tflD FFFC 




LOOOl 


TST.L 


|FFFC<A5) 








000098 6C00 FF7C 






BQE 


L0002 


0)000016 


2a 


16 -1 


UNTIL 


ArguMent<0; 












00009C aEBA 0000 






JSR 


XTERM 








OOOOW) 4E5D 






UNLK 


AS 








0000A2 aEBA 0000 






JSR 


X1_END 








0O00A6 aE75 






RTS 










QOQOm OESE 






UNIX 


A6 








OOOOAA aE75 






RTS 










OnOOAC C558 4140 504C 




.VORO 


$C558,|414D,|504C 


; ".mfs>\ 






000(»2 4520 






.vora) 


$4520 


; "E " 






000084 0022 




Cstsize 


.VORD 


L3St-CstSize-2 








000(S6 




CstOTOl 












000086 03 






.BYTE 


3 








000(»7 2920 3D 






.ASCII 


') =' 








OOOOBA 




CSt0002 












00008A OA 






.BSTE 


10 








OJOOBB 4661 6374 6F72 




.ASCII 


•Factor" 








OOOOCl 6961 6C28 






.ASCII 


■iaic 








0O0OC5 00 






-BYTE 


V» 








0000C6 




CSt0003 












0O0OC6 10 






.BYTE 


16 








0O0OC7 456E 7465 7220 




.ASCII 


■Enter ' 








OOOOCD 6172 6775 6065 




.ASCII 


'arome* 








000CH}3 6E74 3A20 






.ASCII 


•nt: • 








0000D7 00 






-BYTE 


$00 








0000D8 




Last 
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25 17-0 END. {Exanpie} 

Elapsed compilation tine: 1.483 seconds. 
Corpilation conplete - no errors found. 25 lines. 
Elapsed code generator tine: 3.106 seconds. 
Total code size = 28fl 
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LISTING FORMAT #4 - Full listing f ormflt with the $ASM PROC in effect 



Lisa Pascal conpiier V3.22 (i4-Jun-8a) 

Lisa Pascal i«68000 code Generator V3.14 (ia-3un-8a) 



13:31:43 i5-Jun-8« 
13:38:3« 15-Jun-8« 



1 

2 
3 




1 


PROGRAM Example; 








3 


VAR 






a 




a 


Argument: Longint 


• 




5 




5 


— 






6 




6 


($1 Factorial) 






7 




1 


— A FUNCTION FactoriaKArg: Longint): Longint; 


8 




2 


— 






9 




3 0- A BEGIN {Factorial } 






10 




a 


IF Arg<=l TfffN 






11 




5 


Factorial : 


= 1 




12 




6 


ELSE 






13 




7 


Factorial : 


= Arg*Factorial<Arg-l); 


14 




8 


-0 A El«); {Factorial) 












000000 4A6F FOOO FACTC«IA TST.W 


$F000(A7> 








OOOtMM 4E56 0000 


LINK 


A6,«$0000 








000)03 OCAE 00)0 0)01 


CMPI.L 


«$00000001,$0008(ft6) 








OOOOOE 0008 












000010 6E08 


BGT.S 


LOOOl ; OOOraOiA 








OC»012 7001 


MOVEQ 


«$01,D0 








000014 2D40 OOOC 


MO'^.L 


D0,$0O)C<A6) 








000018 601A 


BRA.S 


LM)02 ; 00000034 








OOOOIA 42A7 LOOOl 


CLR.L 


-(A7) 








OOOOIC 202E 0008 


HOVE.L 


$0008<A6),O) 








000020 5380 


sjeo-L 


«.W.K) 








000022 2F00 


HOVE.L 


D0,-<A7) 








0)0024 4EBA 0000 


JSR 


FACTORIA 








000028 2F2E 0008 


MOVE.L 


$0008(A6),-(A7) 








00002C 4EBA 0000 


JSR 


XI MUL4 








000030 2D5F OOOC 


MO\C.L 


(A7)*,$OO0C(ft6) 








00)034 4E5E L0002 


UNLK 


A6 








000036 2E9F 


MOVE.L 


<A7)*,(A7) 








0)0)38 4E75 


RTS 










00003A 0641 4354 «F52 


.V0») 


$C641,$a354,^4F52 ; ".ACTOR' 








a»040 4941 


.VORO 


$4941 ; "lA" 








000042 0000 cstsize 


.«ORD 


Lsist-CstSize-2 








000044 Last 







15 
16 
17 
18 
19 
20 
21 
22 
23 

2a 

25 



7 ~ 

8 0- 

9 1- 

10 ~ 

11 — 

12 — 

13 ~ 

14 ~ 

15 ~ 

16 -1 

17 -0 



BEGIN {Exanple} 
REPEAT 
Write in; 

«rite<* Enter argjMent: '); 
ReacJ<Ai-gunent>; 

IF (IOResult<=0> AND (Argunent>=0> 
WriteLnCFsctorialC Argijnent: 
Factorial (Arqunent): l); 
UNTIL Argjnent<0; 



THEN 

1, •) =■, 



END. {Exanple) 

0)0000 4EBA 00)0 EXA^ff>L£ OSR % BEGIN 

000004 4E56 0000 LINK A6,«|0000 

00)008 2C5F MOVflE.L <A7)*,A6 

iX)0O0A 4E55 FFFC LII>*i A5,«$FFFC 

VXUm. 9FED 0010 SUBA.L $0010<A5),A7 

000012 4EBA 0000 JSR % INIT 

0OM316 2F2D OOOC LD002 MO'^.L $O)0C((iS),-<A7> 



2-': 



Passes} Reference Msnu&I 



Listing F(x-mais 



OOOOIA aEBA 0000 


JSR 


!IW U\ 


OOOOIE 2F2D OOOC 


MOyE.L 


|<»0C(rt5>.-<A7) 


000022 aS7A O0A2 


PEA 


CSt0003 ; 0C»000C6 


000026 «267 


CIR.W 


-<A7) 


000028 aEBA 0000 


JSR 


m STR 


00002C 2F2D 0008 


MOVE.L 


f0O08(A5),-(A7) 


000030 OEBA 0000 


JSR 


%k I 


000034 2B5F FFFC 


MOVE.L 


<A7>+,?FhFC(A5) 


000038 aEBA 0000 


JSR 


% lORES 


00003C aA5F 


TST.W 


(A7)* 


00003E 5FC0 


Sl£ 


DO 


030040 4AAD FFFC 


TST.L 


$FFFC<A5) 


000044 5CC1 


SGE 


Dl 


000046 COOl 


MCi.B 


01, DO 


000048 674A 


6EQ.S 


LOOOl ; 0(M»0094 


00004A 2F2D OOCTC 


MOVE.L 


?000C(A5).-<A7> 


00004E 487A 006A 


PEA 


CStCtt)02 ; OOOOOOBA 


000052 4267 


CIR.W 


-<A7) 


<X)0054 4EBA 0000 


JSR 


Mrf STR 


000058 2F2D OOOC 


HOVE-L 


|00bC(A5),-<A7) 


0OOC6C 2F2D FFFC 


MOVE.L 


$FFFC<A5),-<A7) 


000060 3F3C OOOi 


MOVE.W 


«$0001,-<A7) 


000064 4EBA 0000 


JSR 


9M I 


000068 2F20 OOOC 


MOVE.L 


|OOOC(A5),-(:A7> 


OOtWeC 487ft 0048 


PEA 


CstOOOl ; 000000B6 


000070 4267 


CUl.tf 


-(A7) 


000072 4EBA 0000 


JSR 


Xtf STR 


000076 2F20 OOttJ 


MOVE.L 


$00bC(A5),-<A7) 


00007A 42A7 


CLR.L 


-<A7) 


00007C 2F2D FFFC 


MOVE.L 


$FFFC<A5),-<A7> 


000080 4EBft (XXXi 


JSR 


FACTORIA 


000084 ^30 0001 


MOVE.W 


«|0001.-(A7) 


000088 4E6ft 0000 


JSR 


m I 


00008C 2F2D OOOC 


MOVE.L 


?0O0C(A5),-(A7> 


000090 4EBft 0000 


JSR 


w m 


000094 4AAD FFFC IDOOl 


TST.L 


$FFi='C(A5) 


000098 6C00 FF7C 


BGE 


L0002 ; 00000016 


00009C 4EBft 0000 


JSR 


KTEW1 


OOOOAO 4E5D 


UNLK 


AS 


0OO0A2 4EBft 00(H) 


JSR 


%j.m 


0OOOA6 4E75 


RTS 




0OOOA8 4E5E 


UNIK 


A6 


OOOOftft 4E75 


RTS 




OOOOftC C558 414D 504C 


.WORD 


^C558,*414D,$504C ; ".XAMPI 


0C»082 4520 


.VORO 


^^4520 ; "E " 


oo(K»4 0022 cstsize 


.WORD 


L8i£t-CstSize-2 


0C»OB6 CstOOOl 






0O00B6 03 


.BYTE 


3 


«XM»7 2920 3D 


.ASCII 


■) =• 


OOOCBA CstO(M2 






0C»OBA OA 


.BYTE 


10 


ooocee aeei 6374 6F72 


.ASCII 


■Factor' 


OOOOCl 6961 6028 


.ASCII 


'ialC 


(MOOCS 00 


.BYTE 


$00 


0OO0C6 Cst0003 






0OOOC6 10 


.BYTE 


16 


0OOOC7 456E 7465 7220 


.ASCII 


"Enter * 


OOCKJCD 6172 6775 6065 


-ASCII 


'aj-gune' 


a)00D3 6E74 3A20 


.ASCII 


'nt: ' 


000007 00 


.BYTE 


$00 
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000008 Last 

Elapsed conpilation tine: l.a83 seconds. 
Cofipilation c<»iplete - no errors found. 25 lines. 
Elapsed code generator tine: 2.846 seconds. 
Total code size = 28a 
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LISTING FCMRMAT #5 - Assen*ler inpiA interleaved with Pascal source as 
corraments 

PROjRAM Exawpie; 



VAR 

Argument: Longlnt; 

{^I Factorial) 

FUJCTION Factorial (Arg: Longlnt): Longint; 

BEGIN {Factorial ) 

.FUI« FACTOR I A 



-REF 
-REF 



XI MULA 
FACTORIA 



LOOOl 



Arg*Fac tor i al < Arg-i ) ; 



L0O02 



Cstsize 
Last 



T&T.tf -il096(A7) 
LINK A6,ltO 

IF Arg<=:i THEN 
CMPI.L «1,8(A6) 
BGT.S LOOOl 

Factorial := 
MOVEQ «1,D0 
HOVE.L D0,i2(A6) 
BRA-S L0OO2 

ELSE 

Factorial := 

CLR.L -(A7> 

MOVE.L 8«!»),D0 

SUBQ.L «1,D0 

MOVE.L D0,-(A7) 

JSR FACTORIA 

MOVE.L 8(A6),-<A7) 

JSR IKI MUU 

MOVE.L (A7)*,12(A6) 

UNLK A6 

Mff^E.L (A7)*,(A7) 
RTS 

.WORD $C6ai, 14354, |flF52,|a9fll 

L8i£t-CstSize-2 



END; {Factorial} 



BEGIN {Example} 
FEreAT 

.MAIN EXAMPLE 



.REF 
.REF 
.REF 
-REF 
-REF 
-REF 
.KEF 
.REF 
.REF 
-REF 



% END 

sTterm 

MJ I 

% Tores 
m I 

MW'STR 
!IW~LH 
FACTORIA 
% INIT 

jTbegin 
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U0002 



LlO(X)l 



JSR 


X BEGIN 




um 


A6,«0 




MOVE.L 


CA7)*,A6 




LINK 


A5,«-a 




aJBA.L 


16(A5),A7 




JSR 


% INIT 




Writeui; 




IHTfPE.L 


12(A5),-<A7> 




JSR 


m LN 




VriteCEnter argunent: '); 




MOVE.L 


12<A5>,-(A7) 




PEA 


Cst0003 




CLR.W 


-<A7) 




JSR 


W STR 




Read<Argunent>; 




MOVE.L 


8<A5),-<A7) 




JSR 


DA I 




MO-VE.L 


<A7)*.-4(A5) 




IF (IOResuit<=0) AT© <ArguMent>=0) 


THEN 


JSR 


% lORES 




TST.W 


CA7)H- 




SLE 


00 




TST.L 


-a(ft5) 




SGE 


Dl 




AND.B 


Di,D0 




BEQ.S 


LOOOl 




MritelnCFactoriaiC, Argument: 


i, •) 




Factonsil(Argunent): l>: 




MOVE.L 


12(A5),-<A7) 




PEA 


C&t0002 




CLR.W 


-<A7) 




OSR 


m STR 




MOVE.L 


12(A5),-(A7) 




MOVE.L 


-a(A5),-(A7> 




MOVE.W 


S1,-<A7) 




OSR 


%i I 




MOVE.L 


12(^),-<A7) 




PEA 


CstOOOl 




CLR.W 


-<A7> 




JSR 


WW STR 




MOVE.L 


i2(A5),-<A7) 




CLR.L 


-<A7) 




MOVE.L 


-fl<A5),-<A7) 




JSR 


FACTORIA 




MOVE.W 


«i,-(A7> 




JSR 


W I 




MOVE.L 


12(fi5),-<A7) 




JSR 


W LN 




TST.L 


-«(A5) 




BGE 


LD002 




JNTIL Argunent<0: 




JSR 


% TERM 




UNLK 


AS 




JSR 


X_EHD 




RTS 






UNIX 


f& 




RTS 







.WORD $C558,$aiaD,$504C,$a520 
CstSize .WORD LBist-C5tSize-2 
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csxxxxn. 

-BYTE 3 

.ftSCIl ') =• 
CSt0002 

.BYTE 10 

.ASCII • Factorial (' 

.BYTE iOO 
Cst0003 

.BYTE 16 

.ASCII 'Enter argunent: 

.BYTE $00 
Last 
; END. {EXdnple} 

.END 
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LISTING FORMAT #6 - Assembler input with the $ASM PROC in efTect 

PROGRAM Exanple; 

te-gunent: Longlnt; 

i%\ Factorial) 

FUNCTION Factorial (Arg: Longlnt): Longlnt; 

BEGIN {Factorial} 
IF Arg<=l THEN 

Factorial := l 
ELSE 

F€Ctorial := Arg*Factorial<ftrg-i>; 
EW; {Factorial} 





-FUNC 


FACTORIA 


' 


-REF 


M Hum 




.REF 


FACTORIA 


' 


TST.W 


-«096<A7) 




Lira<: 


A6,«0 




CMPI.L 


«1,8<A6) 




BGT.S 


LOOOl 




HOVEQ 


»1,D0 




NOVE.L 


D0,12(l«> 




BRft.S 


LD002 


LOOOl 


CLR.L 


-(A?) 




HOVE.L 


8<A6),D0 




SUBQ.L 


«1.D0 




MOVE.L 


D0,-<A7> 




3SR 


FACTORIA 




MOVE.L 


8<A6>,-(A7) 




OSR 


XI nuu 




MOVE.L 


<A7)+,12<A6) 


UD002 


IMLK 


A6 




MOVE.L 


(A7)-, <A7) 




RTS 






.WORD 


$C641, 14354, ?«F52, $4941 


CstSize 


.WORD 


Last-CstSize-2 


Last 






; BEGIN {Exanple) 




REPEAT 






writem; 




Wri tec Enter argunent: '); 




Read(Argunent>; 




IF (lOResiJlt<=0) AND <Argunent>=0> THEN 



writetnCFactorialc Argunent: i. 
Factorial (Argunent): i); 
UNTIL Argunent<0; 
EM). {Exanple) 

.MAIN EXAMPLE 

.REF \ END 
.REF X~TERM 
.REF W I 
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iJ0002 



LDOJl 



.KEF 


X lORES 


-REF 


mi 


-REF 


SW"STR 


.REF 


«w"ln 


-REF 


FACTMIIA 


.REF 


% INIT 


.REF 


X_BEGIN 


JSR 


X BEGIN 


LINK 


A6,«0 


MOVE.L 


<A7)*,A6 


LINK 


A5,a-fl 


SUBA.L 


16(A5),A7 


JSR 


% INIT 


rravE.L 


12<A5),-(A7) 


JSR 


Xtf LN 


MOVE.L 


12(A5),-<A7) 


PEA 


Cst0003 


CLR.W 


-<A7) 


JSR 


XW STR 


MOVE.L 


8<A5),-(A7> 


JSR 


9tR I 


MOVE.L 


(A7)*,-a<A5) 


JSR 


X lORES 


TST.W 


<A7)+ 


SUE 


tso 


TSr.L 


-a(A5) 


SGE 


01 


Aid .6 


Di,D0 


6EQ.S 


lX»Oi 


MOVE.L 


12(A5),-<A7) 


PEA 


CSt0002 


CLR.W 


-<A7) 


JS* 


Xtf SIR 


MOVE.L 


12(A5),-(A7) 


MOVE.L 


-a(A5),-<A7) 


MCWE-W 


«i,-<A7) 


JSR 


Mf I 


MOVE.L 


12TA5),-(A7) 


PEA 


CStOOOl 


CLR.W 


-<A7) 


JSR 


m STR 


MO-^.L 


12TA5>,-(A7) 


CLR.L 


-<A7) 


MCWE.L 


-a<A5),-(A7) 


JSR 


FACTORIA 


MOVE.W 


«i,-<A7) 


J3} 


XW I 


MOVE.L 


12<A5),-<A7) 


JSR 


Xtf LN 


TS7.L 


-aTA5) 


QGE 


LD002 


JSR 


XTERM 


UNLK 


^ 


JSR 


XJND 


RTS 




UNLK 


m 


RTS 





.WOFD $C558,$aiaD,$50aC,$a520 
Cstsize .WORD L8st-CstSize-2 
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cstoooi 

-B-tTTE 3 

-ASCII •) =• 
C£t0002 

-BYTE 10 

-ftSCII ' Factor ieac 

.BYTE ?00 
Cst0003 

.BYTE 16 

.ASCII 'Enter argunent: 

.BYTE $00 
Last 

.END 
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Please note that the topic references in this index 
are by section number. 

A 

Abs Function 11. 4. 2 

Abs2X D. 4. 3» D. 4. 12 

Absolute value D, 9. 2 

AbsX D. 3. 9, 2, D. 3. 12 

Accuracy in Real Arithmetic D 

ACosX D. 4. 3» D. 4. 12 

Actual -Parameter 5. 2, 7. 1, 7. 3 

syntax 5. 2 
Actual -Parameter-List 5. 2 

syntax 5. 2 
Actual -Parameters in Procedure Call 6.1.2 
Add, D. 3. 3. 1 

AddPtd Procedure E. 9. 17 
AddC, D. 3. 3, 1» D. 3. 12 
AddD D.3.3. 1, D. 3. 12 
Adds D. 3. 3. 1, D. 3. 12 
AddX D. 3. 3. 1, D. 3. 12 
Anomalies in Lisa Pascal B 
Annuity D. 3. 10. 3, D. 3. 12 
Apple II Pascal A 
Apple III Pascal A 
Apple II and Apple III Pascal: Other Differences 

A. 3 
Apple Numerics Manual D. 1 
Applestuff Unit A 
Arc, Graphic Operations E. 9. 10 
Arctan Function 11. 4. 9 
Arctangent D. 3. 10. 4 
Arithmetic Functions 11. 4 
Arithmetic Operations D. 3. 3 
Arithmetic c4)erators 5. 1. 2, D 
Array 3. 2. 1, 4. 3. 1 

component 3. 2. 1, 4. 3. 1 

reference 4. 3. 1 
Arrays and Matrices D. 4. 10. 3 
Array-type 3. 2. 1 

syntax 3. 2. 1 
Ascent Line E. 5. 2 
ASCII 3.1,1.5 
ASinX D. 4. 3. D. 4. 3, D. 4. 12 
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Assembler Input Source J-2 
Assembler Input by Source J-3 
Assemably Language D. 5. 1 
Assembly Language, Quickdrav E. 11 
6502 Assembly-Language SANE Engine D. 1 
68000 Assembly-Language SANE Engine D. 1 
Assignment -Compatibility 3.4.3 
Assignment-Statement 6. 1. 1 

syntax 6. 1. 1 
ATanX D. 3. 10. 4, D. 3. 12 
ATan2X D. 4. 3, D. 4. 12 
Auxiliary Procedures D. 3. 9 

B 

BackColor Procedure E. 9. 5 
BackPat Procedure E. 9. 1 
Base-2 logarithm D. 3. 10. 1 
Base Line E. 5. 2 
Base-Type 3. 2. 3, 3. 3, 5. 3 

of pointer-tj^e 3. 3 

syntax 3. 3 

scope anomaly B 

of set-type 3. 2. 3, 5. 3 
Basic Listing Formats J-1 
Beep Procedure F. 4 
Binary Log D. 3. 9. 4 
Binary Scale D. 3. 9. 4 
Bit Image E. 4. 1 

Bit Transfer Operations E. 9. 13 
BitMap Data Type E. 4. 2 
Bitmaps E. 4. 2 

Bitwise Boolean Operations A 
Blank Character 1. 1 
Blank Segment 8. 3, 9. 1 
Block 2 

syntax 2. 1 
Block-structured I/O 3. 2. 4. 

10.1.1-2, 10.4 
Blockread Function 3. 2. 4, 10. 4. 1 
Blockwrite function 3. 2. 4. 10. 4. 2 
Boolean 3. 1. 1. 4, 5. 1. 3, 5. 1. 5. 2, 

10.3.3.7, 12.3-12.4 

comparisons 5.1.5.2 

constants as control values 12. 3. -4 
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operands, evaluation of 5. 1. 3 

operators 5. 1. 3 

data type 3. 1. 1. 4 

values in text-oriented output 
10. 3. 3. 7 
Boundary Rectangle E. 4. 2 
Boxes Program E. 14. 2 
Buffer Variable 10. 1. 3. 10. 1. 7 
Built-in Procedures and Functions 10, 

11 
Busy Cursor F. 2. 2 
BusyDelay Procedures F. 2. 2 
Busylmage Procedures F. 2. 2 
Byte Array 11. 7 
Byte-Oriented Procedures and Functions 

11.7 
Byte-Size Files 3. 2. 4 
Bytestream Type A 



C 

C2Dec D. 3. 4. 2, D. 3, 12 
C2Str D. 3. 4. 2, D. 3. 12 
C2X D. 3. 4. 1. D. 3. 12 
Camera Eye E. 12 
Case 6. 2. 2. 2 

syntax 6. 2. 2. 2 
Case-Constant in Case Statement 

6. 2. 2. 2 
Case-Sensitivity 1. 1, 1. 2, 1. 4 
Case-Statement 6. 2. 2. 2, Notes 6-1 

efficiency 12. 5 

syntax 6. 2. 2. 2 
Char 1. 6. 1, 3. 1. 1. 5, 10. 3. 1. 1, 
10.3.3.2, 11.5 

constant 1. 6. 1 

type 3. 1. 15 

values in text-oriented I/O 
10.3.1.1, 10.3.3.2 
Character 1. 1. 3. 2. 4. 4. 3. 1 

device 3. 2. 4, 10. 1. 1-2 

files 3.2.4 

font E. 5. 2 

in string 4. 3. 1 
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set 1.1 
Character Style E. 5. 2 
CharWidth Function E. 9. 4 
Chr Function 11.5.2 
Class Functions D. 3. 7. 1 
ClassC D. 3. 7. 1, D. 3. 12 
ClassD D. 3. 7. 1, D. 3. 12 
ClassS D. 3. 7. 1, D. 3. 12 
ClassX D. 3. 7. 1, D. 3. 12 
ClearHlts D. 4. 2, D. 4. 12 
ClearXcps D. 4. 2, D. 4. 12 
Clip30 Function E. 12. 4 
ClipRect Procedure E. 9. 1 
ClipRgn E. 5 

Clock/Calendar F. 8, F. 9 
Close Procedure 10. 1. 5 
ClosePicture Procedure E. 9. 14 
ClosePoly Procedure E. 9. 15 
ClosePort Procedure E. 9. 1 
CloseRgn Procedure E. 9. 11 
Closing a File 10. 1. 5 
CmpX D. 3. 6, D. 3. 12 
Code Generation 12. 1 

Code Generator Invocation Options Notes 12-4 
Code Generator Invocation Options (Table) 

Notes 12-7 
Color Drawing E. 7. 2 

routines E. 9. 5 
ColorBit Procedure E. 9. 5 
Column Pivoting D. 4. 10. 9 
Comment 1. 8 
Comp D. 3. 2, D. 3. 12 

Comparison to Apple II and Apple III Pascal 
Comparison Functions D. 3. 6 
Comparisons 5. 1. 5 
Comparisons Involving NaNs D. 2. 4 
Compatibility of Parameter Lists 

7.3.5 
Compatible Types 3. 4 
Compile-Time Expressions and Variables 

12. 2. 1-3 
Compiler 1. 8, 12, A 

commands 1. 8, 12. 1-2, A, Notes 12-1 
Compiler Commands CTable] Notes 12-7 
Compiler Invocation Options Notes 12-2 
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Compiler Invocation Options (Table] Notes 12-7 
Component of Array 3. 2. 1, 4. 3. 1 
Component of File 3.2.4, 4.3.3 
Component -Type of Array 3. 2. 1 
Component-Type of File 3. 2. 4 
Composing Transformations D. 4. 10. 3 
Compound D. 3. 10. 3, D. 3. 12 
Compound Interest D. 3. 10. 3 
Compound-Statement 6. 2. 1 

syntax 6. 2. 1 
Concat Function 11. 6. 3 
COND D. 4. 10. 4 

Conditional Compilation 12. 2 
Conditional-Statement 6. 2. 2 

syntax 6. 2. 2 
Conditioned Problems D. 4. 10. 4 
Condition number D. 4. 10. 4, D. 4. 10. 10 
Constant 1. 4-7 

syntax 1. 7 
Constant-Declaration 1. 7, 2. 1, B 

scope anomaly B 

syntax 1. 7 
Constant-Declaration-Part 2. 1 

syntax 2. 1 
Constant Expressions Notes 1-1 
Constants, Assembly Language E. 11. 1 
Contrast Control F. 3. 1 
Contrast Function F. 3. 1 
Control-Variable 6. 2. 3. 3 

syntax 6. 2. 3. 3 
Conversion, Tj^e Notes 3-1 
Conversions D. 3. 4 

Conversions To and From Extended D. 3. 4. 1 
Conversions Between Binary and Decimal D. 3. 4. 2 
Converting Decimal Strings into SANE Types 

D. 3. 4. 2 
Converting SANE Types into Decimal Strings 

D. 3. 4. 2 
Coordinate Conversion D. 4. 3 
Coordinate Plane E. 3. 1 
Coordinates, GrafPort E. 3. 1. E. 6 
Copy Function 11. 6. 4 
CopyBits Procedure E. 9. 13 
CopyRgn Procedure E. 9. 11 
Correctly Rounded Conversion D. 4. 7 
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Correlation Matrix D. 4. 10. 7 

Cos Function 11. 4. 5 

CoshX D. 4. 3, D. 4. 3, D. 4. 12 

CosX D. 3. 10. 4, D. 3. 12 

Cosine D. 3. 10. 4 

CpySgnX D. 3. 9. 2, D. 3. 12 

CR Character 1. 1, 1. 6, 10. 3 

in text-oriented I/O 10. 3 
Crunch 10. 1. 5 
Current Block Number 10. 4 
Current File Position 4. 3. 3 
Cursor Control 10. 3. 7, F. 2 
Cursor Data Type E. 4. 4 
Cursor-Handling Routines E. 9. 2 
CursorHeight Data Type F. 10 
Curs or I mage Procedure F. 2 
CursorLocation Procedure F. 2. 1 
CursorPtr Data Type F. 10 
Cursor, QuickDraw E. 4. 4 
CursorTracking Procedure F. 2. 1 
Customizing QuickDraw Operations 

E. 10 



D 
















D2Dec D. 3. 4. 2, 


D. 


3. 


12 








D2Str D. 3. 4. 2. 


D. 


3. 


12 








D2X 


D. 3. 4. 1. 


D. 


3. 


12 








Data 


Bitmap F. 


2 












Data 


Types D. 2 


1.2 












Data 


Types 3 
















assembly 


language 


E. 


11. 


2 




GrafSO E. 


12. 


3. 


E. 


13. 


5 





QuickDraw E. 2. 2, E. 13. 2 
DataFile 10. 1. 2 
Date F. 8, F. 9 
DateArray Data Type F. 10 
DateTime Procedure F. 8 
DateToTime Procedure F. 8 
DblPrecision D. 4. 12 
Dead Key Diacriticals F. 5. 4 
Debugging 12. 1 
Dec2C D. 3. 4. 2, D. 3. 12 
Dec2D D. 3. 4. 2, D. 3. 12 
Dec2S D. 3. 4. 2, D. 3. 12 
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Dec2X D. 3. 4. 2, D. 3. 12 

DecForm D. 3. 4. 2, D. 3. 12 

Decimal D. 3. 4. 2, D. 3. 12 

Decimal Record Conversions D. 3. 4. 2 

Decimal Record Type D. 3. 4. 2 

DecStr D. 3. 4. 2, D. 3. 12 

DECSTRLEN D. 3. 12 

Defining Declaration 7. 1 

Delete Procedure 11. 6. 5 

Deletions A. 2 

DENORMAL D. 3. 7. 1, D. 3. 12 

Denormalized number D. 3. 7. 1 

De normalized Numbers D. 3. 7 

Descent Line E. 5. 2 

Determinant D. 4. 10. 10 

Determinants D. 4. 10. 5 

Device 10. 1. 1-2 

character 10. 1. 1, 10. 1. 2 

file-structured 101. 1, 10.1.2 

types 10. 1. 1, 10. 1. 2 
Diacritical Marks F. 5. 4 
DiffRgn Procedure E. 9. 11 
Digit 1.1 

Digits D. 3. 4. 2, D. 3. 12 
Digit-Sequence 1. 4 

syntax 1. 4 
DimContrast Function F. 3. 2 
Dimensions of Lisa Screen E. 4. 1 
Directive 1. 3 

Diskette Insertion Switches F. 5 
Display Screen F. 3 
DisposeRgn Procedure E. 9. 11 
DIVBYZERO D. 3. 8. 2. D. 3. 12 
Div Operator A 
DivC D. 3. 3. 1, D. 3. 12 
DivD D. 3. 3. 1. D. 3. 12 
DivS D. 3. 3. 1, D. 3. 12 
DivX D. 3. 3. 1, D. 3. 12 
Divide D. 3. 3. 1 
Division by Zero (Real Arithmetic) 

3.1.1.3. D 
DLE Character 10. 3 
Double D. 3. 2. D. 3. 12 
DblPrecision D. 4. 2 
DOWNWARD D. 3. 8. 1, D. 3. 12 
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DravChar Procedure E. 9. 4 
Drawing E. 7 

color E. 7. 2 
DrawPicture Procedure E. 9. 14 
DrawString Procedure E. 9. 4 
DrawText Procedure E. 9. 4 
Dynamic Allocation Procedures 11. 2 
Dynamic storage D. 4. 4 

E 

Efficiency, Case-Statements 12. 5 

E format D. 4. 6 

ELEMS D. 3. 12 

Elementary Functions D. 3. 10, D. 4. 3 

Empty Set 5. 3 

EmptyRect Function E. 9. 6 

EmptyRgn Function E. 9. 11 

Enumerated-Type 3. 1. 2 

syntax 3, 1. 2 
Environ D. 3. 8. 2, D. 3. 12 
Environmental Control D. 3. 8 
Eof Function 10. 1. 7 

and various procedures 10. 1. 3-4, 

10.1.7. 10.2.1-2. 10.2.4, 

10.3.1-2, 10.4.1 
Eoln Function 10. 3. 5 

and read and readln procedures 

10.3.1, 10.3.2 
EQ D. 3. 6, D. 3. 12 
Equal D. 3. 6 

EqualPt Function E. 9. 17 
EqualRect Function E. 9. 6 
EqualRgn Function E. 9. 11 
EraseArc Procedure E. 9. 10 
EraseOval Procedure E. 9. 8 
ErasePoly Procedure E. 9. 16 
EraseRect Procedure E. 9. 17 
EraseRgn Procedure E. 9. 12 
EraseRoundRect Procedure E. 9. 9 
Error Messages H 
Error Reporting H. 1 
ETX Character A 
Euclidean Length D. 4. 10. 3 

E^ - 1 D. 3. 10. 2 
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Exception D. 3. 8. 2, D. 3. 12 
Exception Flags D. 3. 8. 2 
Existence D. 4. 10.3 
Exit Procedure 11. 1. 1, A 
Exp D. 3. 4. 2, D. 3. 12, D. 4. 7, D. 4. 12 
Exp Function 11. 4. 6 
Exponential format D. 4. 6 
Exponentials D. 3. 10. 2 
ExplX D. 3. 10. 2, D. 3. 12 
Exp2X D. 3. 10. 2, D. 3. 12 
ExpX D. 3. 10. 2, D. 3. 12 
Expression Evaluation D. 3. 5 
Expressions 5 
syntax 5 
Extended D. 3. 2, D. 3. 12 
Extended Comparisons A 
Extended Temporaries D. 3. 5 
Extended-Based Expression Evaluation D. 3. 5 
Extensions A. 1 
External File 10. 1 
External Function 7. 2 
External Procedure 7. 1-2 
External Rate of Return D. 4. 9 
ExtPrecision D. 4. 12 

F 
Factor 5 

syntax 5 
FadeDelay Function F. 3. 2 
F format D. 4. 6 

Field of Record 3. 2. 2, 4. 3. 2, 6. 2. 4 
Field-Declaration 3. 2. 2 

syntax 3. 2. 2 
Field-Designator 4. 3. 2 

syntax 4. 3. 2 
Field-List 3.2.2 

syntax 3. 2. 2 
File 3. 2. 4. 4. 3. 3. 10 

buffer 4. 3. 3 
Buffer and Eof Function 10. 1. 7 
Buffer and Reset Procedure 10. 1. 3 
Component 3.2.4, 4.3.3 
Identifier As Parameter Type 7. 3 
Of Char 3. 2. 4 
Position and Reset Procedure 
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10.1.3 
Record 10. 2 
Reference 4. 3. 3 
Species 10. 1. 2 
Standard File-Type Identifier 

3.2.4, 10.1, 10.4 
Types and Reset Procedure 10. 1. 3 
Variable 3. 2. 4, 4. 3. 3, 10 
File -Buffer-Symbol 4.3.3 

syntax 4. 3. 3 
File-Structured Device 3.2.4, 

10.1.1-2. 10.4 
File-Type 3.2.4 

syntax 3. 2. 4 
Fill Arc Procedure E. 9. 10 
FillChar Procedure 11.8.3 
FillOval Procedure E. 9. 8 
FillPoly Procedure E. 9. 16 
FillRect Procedure E. 9. 7 
FillRgn Procedure E. 9. 12 
FillRoundRect Procedure E. 9. 9 
Final-Value 6. 2. 3. 3 

syntax 6. 2. 3. 3 
Financial Analysis D. 4. 8 
Financial Functions D. 3. 10 
Finite Real Values 3. 1. 1. 3 
Fin-Npv D. 4. 8] D. 4. 12 

Fin-Return D. 4. 8, D. 4. 12 
FIXEDDECIMAL D. 3. 4. 2, D. 3. 12 
Fixed Decimal Point Format D. 4. 6 
Fixed-Part 3.2.2 

syntax 3. 2. 2 
Fixed-Point Output of Real Value 

10. 3. 3. 4 
FLOATDECIMAL D. 3. 4. 2, D. 3. 12 
Floating-Point Arithmetic D 
Floating-Point Output of Real Value 

10.3.3.4, A 
Font Numbers E. 15 
Fonts E. 5. 2 
For-Statement 6. 2. 3. 3 

syntax 6.2.3.3 
ForeColor Procedure E. 9. 5 
Foreign Characters F. 5. 4 
Formal -Parameter-Li St 7. 3 
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syntax 7. 3 
Formal -Parameters and Procedure Call 

6.1.2 
Forward Declaration 7. 1-2, Notes 7-1 
FP68K D. 4. 5 

FP-Free-ASCII D. 4. 6. D. 4. 12. 
FPLib D. 1. D. 3. D. 3. 12, D. 5. 3 
FP-New D. 4. 4, D. 4. 12 
FP-Size D. 4. 4, D. 4. 12 
FP-Type D. 4. 4 D. 4. 12 
FPUnit D. 5. 3 

FrameArc Procedure E. 9. 10 
FrameCounter Function F. 3 
FrameOval Procedure E. 9. 8 
FramePoly Procedure E. 9. 16 
FrameRect Procedure E. 9. 7 
FrameRgn Procedure E. 9. 12 
Frame RoundRect Procedure E, 9. 9 
Frames Data Type F. 10 
Free Fomat D. 4. 6, D. 4. 12 
Free Format Conversion D. 4. 6 
Full Listing J-2 
Full Listing By Procedure J-2 
Full Rank D. 4. 10. 2 
Function 7.2-3 
Function-Body 7. 2 

syntax 7. 2 
Function-Call 5, 5. 2, 7. 2, 7. 3 

syntax: 5. 2 
Function-Declaration 7. 2 

syntax 7. 2 
Function-Heading 7. 2 

syntax 7. 2 
Functional Parameter 7. 3. 4 
Functions, Assembly Language E. 11. 4 
Future Value D. 3. 10. 3 



B 

GE D. 3. 6, D. 3. 12 

GEL D. 3. 6, D. 3. 12 

Get Procedure 10.2.1, 10.2.3 

GetClip Procedure E. 9. 1 

GetEnv D. 3. 8. 2, D. 3. 12 
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Get Font Info Procedure E. 9. 4 

GetHltAddress D. 3. 11, D. 3. 12 

GetPen Procedure E. 9. 3 

GetPenState Procedure E. 9. 3 

GetPixel Function E. 9. 18 

GetPort Procedure E. 9. 1 

GetPort30 Procedure E. 12. 4 

GetPrecision D. 4. 2, D. 4. 12 

GetRnd D, 3. 8. 1, D. 3. 12 

GL D. 3. 6, D. 3. 12 

Global Coordinated E. 6, E. 9. 17 

Global Constants D. 3. 5. 1 

Global Variables, Assembly Language 

E. 11. 3 
GlobalToLocal Procedure E. 9. 17 
Goto-Statement 6. 2, A 

syntax 8. 1. 3 
Gotoxy Procedures 10. 3. 7. 2 
Graf 30 E. 12 

data types E. 12. 3, E. 13. 5 

sample program E. 14. 2 
Graf Device Procedure E. 9. 1 
GrafPort Coordinates E. 3. 1, E. 6 
GrafPort Data Type E. 5 
GrafPort Routines E. 9. 1 
GrafPorts E. 5 
GrafPtr Data Type E. 5 
GrafVerb Data Type E. 10 
Graphic Pen E. 5. 1 
Greater than D. 3. 6 
Greater than or equal D. 3. 6 
Greater than or less than D. 3. 6 
Greater than, equal, or less than D. 3. 8 
GT D. 3. 6, D. 3. 12 

H 

Halt Address D. 3. 11 
Halt Procedure 11. 1. 2, A 
Halts D. 3, 8. 2 
Halt Vector D. 3. 8. 2 
Handles E. 3. 4 

picture E. 8. 1 

polygon E. 8. 2 

region E. 3. 4 
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Hardware Interface F 

Hardware Interface, Linking To Notes F-1 

Heap 11. 2, D. 4. 4 

Heapresult Function 11. 2. 2 

Hex-Digit 1. 1 

Hex-Digit-Sequence 1. 4 

syntax 1. 4 
Hexadecimal Constants 1. 4 
HideCursor Procedure E. 9. 2 
HidePen Procedure E. 9. 3 
Horner's Method D. 4. 9 
Horner's Rule D. 3. 5 
Host Program or Unit 9 
Host-Type of Subrange 3. 1. 3 
Hotspot E. 4. 4, F. 2 
Hourglass Cursor F. 2. 2 
Hyperbolic Cosine D. 4. 3 
Hyperbolic Sine D. 4. 3 
Hyperbolic Tangent D. 4. 3 



I 

I2X D. 3. 4. 1, D. 3. 12 
Identical Types 3. 4 
Identifier 1. 2 

of program 8. 1 

syntax 1. 2 
Identifier-List 3. 1. 2 

syntax 3. 1. 2 
Identity Procedure E. 12. 4. 2 
IEEE Arithmetic D. 2. 1 
IEEE Standard D. 3. 1 
IEEE Standard D. 3. 1 
If-Statement 6. 2. 2. 1 

optimization 12. 3 

syntax 6. 2. 2 
Implementation-Part 9. 1. 1 

syntax 9. 1. 1 
In Operator 5. 1. 5. 5 
Index 4. 3. 1 

in variable-reference 4. 3. 1 

syntax 4. 3. 1 
Index-Type 3. 2. 1 

syntax 3. 2. 1 
INEXACT D. 3. 8. 2, D. 3. 12 
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INF D. 2. 1 

IFINITE D. 3. 7. 1, D. 3. 12 
Infinities 3. 1. 1. 3, D. 3. 7 
Infinities D. 3. 7 
Infinity D. 2. 1 D. 3. 7. 1 
InitCursor Procedure E. 9. 2 
InitFPLib D. 3. 11, D. 3. 12 
InitGraf Procedure E. 9. 1 
Initial-Value 6.2.3.3 

syntax 6. 2. 3. 3 
Initialization-Part A 
InitPort Procedure E. 9. 1 
Inline Declaration Notes 7-1 
Input (Standard File] 10.1.7, 10.3 
Input File Control [In Compilation) 

12.1 
Input Variables in Read Procedure 

10. 3. 1 
Input/Output 10, Notes 10-1 
Inquiries D. 3. 7. 1 
Insert Procedure 11. 6. 6 
InsetRect Procedure E. 9. 6 
InsetRgn Procedure E. 9. 11 
Int-EForm D. 4. 6, D. 4. 12 

Integer 1.4, 3.1.1.1-2, 10.3.1.2, 
10.3.3.3, 11.3-5, D 

arithmetic 3. 1. 1. 1, 3.1.1.2 

constant 1. 4 

conversion overflow D 

data type 3. 1. 1. 1, 3. 1. 1. 2 

data type conversions 3. 1, 
3.1.1.5, 3.1.2, 11.5.1 

values in text-oriented I/O 
10.3.1.2, 10.3.3.3 
Interactive File-Type A 
Integral format D. 4. 6 
Interface D. 3. 12 
INTERFACE D. 4. 12 
Interface-Part 9. 1. 1 

syntax 9. 1. 1 
IRR D. 4. 8 

Internal Rate of Return D. 4. 8 
Intrinsic Libraries Notes 9-3 
Intrinsic-Unit Syntax Notes 9-2 
INTRINSIC. LIB 9.2, 12.1 
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INVALID D. 3. 8. 2. D. 3. 12 

Invalid Operations in Real Arithmetic 

Inverse D. 4. 10. 1 

Inverse cosine D. 4. 3 

Inverses D. 4. 10. 3 

Inverse sine D. 4. 3 

Invert Arc Procedure E. 9. 10 

InvertOval Procedure E. 9. 8 

InvertPoly Procedure E. 9. 16 

InvertRect Procedure E. 9. 7 

InvertRgn Procedure E. 9. 12 

InvertRoundRect Procedure E. 9. 9 

loresult Function 10. 1. 2, 10. 1. 6 

lOSFPLib D. 1, D. 4 

lOSPasLib D. 1 

Iteritive Improvement D. 4. 10. 6 

K 

Key State F. 5. 3 
KeyboEvent Function F. 5. 3 
Keybold Data Tj^e F. 10 
KeyboPeek Function F. 5. 3 
KeyboQIndex Data Type F. 10 
Keyboard 3. 2. 4, 10. 1. 1, 10. 3. 
10. 3. 7. 1, F. 5 

attributes F. 5. 1 

echoing on input 10. 3 

events F. 5. F. 5. 3 

identification F. 5. 1 

layouts F. 5. 1 

legends F. 5. 1 

physical 3. 2. 4, 10. 1. 1, 10. 3, 
10. 3. 7. 1 

queue F. 5. 3 

repeats F. 5. 5 

state F. 5. 1 

testing 10. 3. 7. 1 
Keyboard Function F. 5, 1 
KeyCap Data Type F. 10 
KeyCapSet Data Type F. 10 
Keycodes F. 5 
KeyEvent Data Type F. 10 
KeylsDown Function F. 5. 2 
KeyMap Procedure F. 5. 2 
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Keypress Function 10. 3. 7. 1 
Keystate F. 5. 3 

KillPicture Procedure E. 9. 14 
KillPoly Procedure E. 9. 15 

L 

L2X D. 3. 4. 1, D. 3. 12 

Label 1.5, 2.1, 6 

on statement 6 

syntax 2. 1, 6 
Label -Declaration-Part 2. 1 

syntax 2. 1 
LDec2X D. 4. 7, D. 4. 12 
LE D. 3. 6, D. 3. 12 
Legends Function F. 5. 1 
Length Attribute 3. 1. 1. 6 
Length Function 11. 6. 1 
Less than D. 3. 6 
Less than or equal D. 3. 6 
Letter 1. 1 

Libraries, Intrinsic Notes 9-3 
Linear Algebra D. 4. 10 
Linear Algebra Procedures D. 4. 10. 8 
Linear Equations D. 4. 10. 3 
Linear Least Squares D. 4. 10. 3 
Lineat Least Squares Problems D. 4. 10. 9 
Line-Drawing Routines E. 9. 3 
Line Procedure E. 9. 3 
Line2D Procedure E. 12. 4 
Line3D Procedure E. 12. 4 
LineTo Procedure E. 9. 3 
LineTo2D Procedure E. 12. 4 
LineTo3D Procedure E. 12. 4 
Linker 7.1 
Linking D. 1 

Lisa Extended Caracter Set G 
Listing Control 12. 1 
Listing Formats J 
Ln Function 11. 4. 7 
Local Coordinates E. 6, E. 9. 17 
LocalToGlobal Procedure E. 9. 17 
Lock 10. 1. 5 
Logarithms D. 3. 10. 1 
LogbX D. 3. 9. 4. D. 3. 12 
Loge (1 + x) D. 3. 10. 1 
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Log2X D. 3. 10. 1. D. 3. 12 
LnX D. 3. 10. 1, D. 3. 12 
LnlX D. 3. 10. 1. D. 3. 12 
LongDecimal D. . 4. 7. D. 4. 12 
Long Integer Data type A 
Longint 1.4, 3.1.1.2, 10.3.1.2, 
10.3.3.3. 11.3-5, D 

arithmetic 3. 1. 1. 2 

constant 1. 4, 1. 6. 1. 7 
11. 3. 4 

data type 3. 1. 1. 2 

data type conversions 11. 3. 3, 

values in text-oriented I/O 
10. 3. 3. 3 
LongSigDig D. 4. 7, D. 4. 12 
LookAt Procedure E. 12. 4. 1 
LSigDigLen D. 4. 7. D. 4. 12 
Lt D. 3. 6, D. 3. 12 



M 

Macintosh D. 1 

Macintosh Code Generation Notes 12-6 

Macintosh Floating-Point Programming D. 4. 5 

Macvkorks D. 5 

Managing Environmental Settings D. 3. 8. 3 

ManyPixels Data Type F. 10 

MapPoly Procedures E. 9. 18 

MapPt Procedure E. 9. 18 

MapRect Procedure E. 9. 18 

MapRgn Procedure E. 9. 18 

Mark D. 4. 4 

Mark Procedure 11. 2. 3. A 

Mask Bitmap F. 2 

MathLib D. 1, D. 4. D. 4. 12, D. 5. 3 

Math-Solve D. 4. 9, D. 4. 12 

Math Sort D. 4, 5 

Math-Sort D. 4. 5» D. 4. 12 

MathUnit D. 5. 3 

Mat-Mult D. 4. 10. 8, D. 4. 12 

Matrix D. 4» 10. 3 

Matrix Multipication D. 4. 10. 3, D. 4. 10. 8 

Maxint 3. 1. 1. 1 

MaxSig D. 4. 5, D. 4. 12 

Memavail Function 11.2.5 
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Member-Group 5. 3 

syntax 5. 3 
Memory Allocation Procedures 11. 2 
Merge sorting D. 4. 5 
Microsecond Timer F. 6 
Microseconds Data Type F. 10 
MicroTimer Function F. 6 
Millisecond Timer F. 7 
Milliseconds Data Type F. 10 
Minimum Listing J-2 
Missing Symbol E. 5. 2 
Mod Operator A 
Mouse F. 1 

button F. 5 

plug F. 5 
Mouse Location Procedures F. 1. 1 
MouseOdometer Procedure F. 1. 4 
MouseScaling Procedure F. 1. 3 
MouseThresh Procedure F. 1. 3 
MouseUpdates Procedure F. 1. 2 
Move Procedure E. 9. 3 
Move2D Procedure E. 12. 4 
Move3D Procedure E. 12. 4 
Moveleft Procedure 11. 7. 1 
MovePortTo Procedure E. 9. 1 
Moveright Procedure 11. 7. 2 
MoveTo Procedure E. 9. 3 
MoveTo2D Procedure E. 12. 4 
MoveTo3D Procedure 
MulC D. 3. 3. 1, D. 3. 12 
MulC D. 3. 3. 1, D. 3. 12 
MulS D. 3. 3. 1, D. 3. 12 
MulX D. 3. 3. 1, D. 3. 12 
Multiply D. 3. 3. 1 

N 

NaN D. 2. 1 

NaN Arithmetic D. 2. 4 

NaN Code D. 2. 1 

NaNCond D. 4. 11 

NaNDet D. 4. 11 

NaNIRR D. 4. 8, D. 4. 11 

NaNs 3. 1. 1. 3, D. 3. 7 

Natural (base-e) logarithm D. 3. 10. 1 
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Negation D. 3. 9. 2 

Negative Zeros D. 2. 1 

NegX D. 3. 9. 2, D. 3. 12 

New Prodedure 3. 3. 11. 2. 1. A 

NewRgn Function E. 9. 11 

Next-After D. 3. 9. 3 

NextD D. 3. 9. 3, D. 3. 12 

NextS D. 3. 9. 3, D. 3. 12 

NextX D. 3. 9. 3. D. 3. 12 

NextRandom D. 4. 3, D. 4. 12 

Nil 3.3, 4.3.4, 11.2.1 

Noise Procedure F. 4 

Nonsingular-transf omations D. 4. 10. 1 

Normal 10. 1. 5 

NORMAL D. 3. 7. 1, D. 3. 12 

Normalized Number D. 3. 7. 1 

Not-a-Number D. 2. 1 

Number 1. 4 

NumClass D. 3. 7. 1, D. 3. 12 

Numerical Comparisons 5. 1. 5. 1 

o 

Object File 9 
Object of Pointer 4. 3. 4 
ObscureCursor Procedure E. 9. 2 
Odd Function 11. 4. 1 
Of f setPoly Procedure E. 9. 15 
Of f setRect Procedure E. 9. 6 
Of f setRgn Procedure E. 9. 11 
0pen3DPort Procedure E. 12. 4 
Opening a File 10. 1, 10. 1. 2-4 
OpenPicture Function E. 9. 14 
OpenPoly Function E. 9. 15 
OpenPort Procedure E. 9. 1 
OpenRgn Procedure E. 9. 11 
Operands 5 

compile-time 12. 2. 3 

in expressions 5 
Operators 5 

compile-time 12. 2. 3 

in expressions 5 
Options, Code Generator Notes 12-4 
Options, Code Generator (Table) Notes 12-7 
Options, Compiler Notes 12-2 
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Options, Compiler (Table) Notes 12-7 
Optimization Of If, Repeat, and While 

statements 12. 3, 12. 4 
Ord Function 3. 1, 3. 1. 1. 5, 3. 1. 2, 

11. 5. 1 
0rd4 Function 3. 1. 1. 2, 11. 3. 3 
Order of Evaluation of Operands 

5. 1. 1 
Ordinal Functions 11. 5 
Ordinal -Type 3. 1 

and ord function 11. 5. 1 

and ord4 function 11. 3. 3 

and pred function 11. 5. 4 

and succ function 11. 5. 3 

syntax 3. 1 
Ordinal-Type-Identifier 3 
Ordinality 3. 1 
Otherwise-Clause 6. 2. 2. 2 

syntax 6. 2. 2. 2 
Output (Standard File) 10. 3 
Output Expression in Write Procedure 

10. 3. 3 
Output File in Write Procedure 

10. 3. 3 
Output-Specs in Write Procedure 

10. 3. 3 
Ovals, Graphic Operations E. 9. 8 
OVERFLOW D. 3. 8. 2. D. 3. 12 
Overflow (Real Arithmetic) 

3.1.1.3, D 

P 

P754 D. 3. 1 

Packed Array of Char 5. 1. 5. 6, 

10.3.1.5, 10.3.3.6, 11.8 

comparisons 5. 1. 5. 6 

fillchar procedure 11. 8. 3 

scanning functions 11. 8. 1, 11. 8. 2 

text-oriented I/O 10. 3. 1. 5, 
10. 3. 3. 6 
Packed Data Types 3. 1. 1. 6, 3. 2 
Page Procedure 10. 3. 6 
Paint Arc Procedure E. 9. 10 
PaintOval Procedure E. 9. 8 
PaintPoly Procedure E. 9. 16 
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Paint Rect Procedure E. 9. 7 
PaintRgn Procedure E. 9. 12 
Paint RoundRect Procedure E. 9. 9 
Parameter 7. 1, 7. 3 

Parameter-Declaration Syntax Notes 7-2 
Parameter List Compatibility 7. 3. 5 
Parameter-Declaration 7. 3 

sjmtax 7. 3 
Parameters in Procedure Call 6. 1. 2 
Pascal Compiler 12 
Pascal Diskette Description 1-6 
Pascal Real Arithmetic D. 5. 2 
Pascal Workshop Files I 
Pattern Data Type E. 4. 3 
Pattern Transfer Mode E. 7. 1 
Patterns E. 4. 3 
Pen E. 5. 1 

Pen Routines E. 9. 3 
PenMode Procedure E. 9. 3 
PenNormal Procedure E. 9. 3 
PenPat Procedure E. 9. 3 
PenSize Procedure E. 9. 3 
Performance Penalty for Longint 

values 3. 1. 1. 2 
PicComment Procedure E. 9. 14 
PicHandle Data Type E. 8. 1 
PicPtr Data Type E. 8. 1 
Picture Comments E. 8. 1 
Picture Data Type E. 8. 1 
Picture Frame E. 8. 1 
Picture Routines E. 9. 14 
Pictures E. 8. 1 
Pitch Procedure E. 12. 4. 2 
Pixtel E. 4. 1 
Pixtels Data Type F. 10 
Plus-EForm D. 4. 6, D. 4. 12 

Point Data Type E. 3. 2 
Pointer 4. 3. 4, 11. 2 
Pointer Function 3. 3, 11. 3. 4 
Pointer-Object-Symbol 4. 3. 4 

syntax 4. 3. 4 
Pointer-Reference 4. 3. 4 
Pointer-Type 3.3 

conversions 11. 3. 3, 11. 3. 4 

syntax 3. 3 
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Pointer-Type -Identifier 3 
Points E. 3. 2 

Points, Calculations E. 9. 17 
Polar Coordinates D. 4. 3 
Polygon Data Type E. 8. 2 
Polygons E. 8. 2 

calculations E. 9. 15 

graphic operations E. 9. 16 
PolyHandle Data Type E. 8. 2 
Polynomial D. 3. 5 
PolyPtr Data Type E. 8. 2 
PorBits E. 5 
PortRect E. 5 

PortSize Procedure E. 9. 1 
Pos Function 11.6.2 
Power Switch F. 5 
P-QR-Record D. 4. 12 
Precedence of Operators 5 
Fred Function 3. 1, 11. h. 4 
Predecessor 3. 1 
Predefined Identifiers A. 4 
Present Value D. 3. 10. 3 
Procedural Parameter 7. 3. 3 
Procedure 7.1, 7.3 
Procedure-and-Function-Declaration- 

Part 2.1 

syntax 2. 1 
Procedure-Body Syntax Notes 7-1 
Procedure-Declaration 7. 1 

syntax 7. 1 
Procedure-Entry D. 3. 8. 3 
Procedure-Exit D. 3. 8, 3 
Procedure-Heading 7. 1 

syntax 7. 1 
Procedure-Statement 6. 1. 2, 7. 1 

syntax 6. 1. 2 
Procedures, Assembly Language E. 11. 4 
ProcEntry D. 3. 8. 3, D. 3. 12 
ProcExit D. 3. 8. 3, D. 3. 12 
Program 8 

identifier 8. 1 

segments 8. 3 

syntax 8. 1 
Program-Heading 8. 1 

syntax 8. 1 
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Program-Parameters 8. 1, 8. 2 

syntax 8. 1 
Pseudo-inverse P D. 4. 10. 3 
Pseudo- inverses D. 4. 10. 1 
Pt2Rect Procedure E. 9. 6 
PtInRect Function E. 9. 6 
PtInRgn Function E. 9. 11 
PtToAngle Procedure E. 9. 6 
Purge 10. 1. 5 
Put Procedure 10. 2. 2-3 
Pwroften Function 11. 4. 10 
Pyramid E. 12 



Q 

QDProcs Data Type E. 10 

QDProcsPtr Data Type E. 10 

QDSample Program E. 2. 1, E. 14. 1 

QDSupport Unit E. 15 

QNAN D. 3. 7. 1, D. 3. 12 

QR-Condition D. 4. 10, D. 4. 10. 10, D. 4. 12 

QR-Determinant D. 4. 10. 8, D. 4. 10. 10, D. 4. 12 

QR-Factor D. 4. 10. 8. D. 4. 10. 10, D. 4. 12 

QR Factorization D, 4, 10. 9 

QR-Improve D. 4. 10. 8, D. 4. 10. 10, D. 4. 12 

QR-Residual D. 4. 10. 8, D. 4. 10. 10, D. 4. 12 

QR-Solve D. 4. 10. 8, D. 4. 12 

QR-Solve finds D. 4. 10. 10 

QR-TransDeterminant D. 4. 10. 8, D. 4. 10. 10, D. 4. 12 

QR-Transolve D. 4. 10. 8, D. 4. 10. 10, D. 4. 12 

Quadratic Equation D. 3, 5 
Qualifier 4, 3 

syntax 4. 3 
QuickDraw E 

QuickDraw Data Types E. 2. 2, E. 13. 2 
QuickDraw Glossary E. 16 
QuickDraw, Linking To Notes E-1 
QuickDraw Routines E. 9 

arcs E. 9. 10 

bit transfer E. 9. 13 

color drawing E. 9. 5 

cursor handling E. 9. 2 

customizing E. 10 

grafPorts E. 9. 1 
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line drawing E. 9. 3 

miscellaneous utilities E. 9. 18 

ovals E. 9. 8 

pen E. 9. 3 

pictures E. 9. 14 

points E. 9. 17 

polygons E. 9. 15, E. 9. 16 

rectangles E. 9. 6, E. 9. 7 

regions E. 9. 11, E. 9. 12 

rounded-corner rectangles E. 9. 9 

text drawing E. 9, 4 

wedges E. 9. 10 
QuickDraw Sample Programs E. 2. 1, 

E. 14 
QuickDraw Summary E. 13 
QuickDraw, Text Notes E-1 
QuickDraw, Using From Assembly 

language £. 11 
Quiet NaN D. 3. 7. 1 
Quo D. 3. 3. 2, D. 3. 12 
Quoted-Character-Constant 1. 6. 1 

syntax 1. 6. 1 
Quoted-String-Constant 1. 6 

syntax 1. 6 

R 

RampContrast Procedure F. 3. 1 
RandModulus D. 4. 3, D. 4. 12 
Random Function E. 9. 18 
Random Number Generator D. 3. 10. 5 
RandomX D. 3. 10. 5, D. 3. 12 
Range-Checking 3. 1. 3, 12. 1 
Rank-Deficient D. 4. 10. 2 
Read Procedure 10. 3. 1 
Readln Procedure 10. 3. 2 
Real 1.4, 3.1.1.3, 10.3.1.3, 
10.3.3.4, 11.3-4, D 

arithmetic D 

constant 1, 4 

data type 3. 1. 1. 3 

data type and round function 11. 3. 2 

values 3. 1. 1. 3 

values and write procedure D 

values in text-oriented I/O 
10.3.1.3, 10.3.3.4, D 
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RealPrecision D. 4. 2, D. 4. 12 
Real -Type 3. 1 

syntax 3. 1 
Real-Type-Identifier 3 
Record 3. 2. 2, 4. 3. 2 

field 3. 2. 2, 4. 3. 2 

number and seek procedure 10. 2. 4 

or file 10. 2 

reference 4. 3. 2 

reference in with statement 6. 2. 4 
Record-Oriented I/O 10.2 
Record-Type 3. 2. 2 

new procedure 11. 2. 1 

syntax 3. 2. 2 
Rectangle Calculation Routines E. 9. 6 
Rectangle Data Type E. 3. 3 
Rectangles E. 9. 9 
Rectangles E. 3. 3 

graphic operations E. 9. 7 
RectlnRgn Function E. 9. 11 
RectRgn Procedure E. 9. 11 
Recursion 7. 1-2 
Redeclaration of Identifier 2. 2. 2, 

2.2.4 
Region Data Type E. 3. 4 

calculations E. 9. 11 

graphic operations E. 9. 12 
Regression D. 4. 10. 7 
Regular-Unit Syntax Notes 9-2 
Relational Operators 5. 1. 5 
Relaxed Order of Declarations Notes 2-1 
Release D. 4. 4 

Release Procedure 11. 2. 4, A 
RelX D. 3. 6, D. 3. 12 
RelOp D. 3. 6, D. 3. 12 
Remainder D. 3. 3. 2 
RemX D. 3. 3. 2, D. 3. 12 
Repeat-Statement 6. 2. 3. 1 

optimization 12. 4 

syntax 6. 2. 3. 1 
Repeating Keys F. 5. 5 
RepeatRate Procedure F. 5. 5 
Repetitive-Statement 6. 2. 3 

syntax 6. 2. 3 
Reserved Words 1. 1 
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Reset Procedure 10. 1, 10. 1. 5, A 
Residual D. 4. 10. 6, D. 4. 10. 10 
Result-Type 7. 2 
syntax 7. 2 
Rewrite Procedure 10. 1. 4 
RgnHandle Data Type E. 3. 4 
RgnPtr Data Type E. 3. 4 
RintX D. 3. 9. 1, D. 3. 12 
Roll Procedure E. 12. 4. 2 
Rotation E. 12 
Round D. 2. 4 

Round Function 11. 3. 2, D 
Rounding D. 2. 2 
RoundDir D. 3. 12 
Rounding Direction D. 3. 8. 1 
Rounding Error D. 4, 9 
Rounding Function D. 3. 8. 1 
Rounding in Real Arithmetic D 
Rounding precision D. 3. 8 
Rounding Direction D. 3. 8. 1. 
RoundDir D. 3. 8. 1 
Roundoff Errors D. 4. 10. 4 
RoundPrecision D. 4. 2, D. 4. 12 
Round to Integral Value D. 3. 9. 1 
Row Width E. 4. 1 

S 

S2Dec D. 3. 4. 2. D. 3. 12 
S2Str D. 3. 4. 2, D. 3. 12 
S2X D. 3. 4. 1, D. 3. 12 
Sane D. 1 

SANE_Environ D. 3. 11, D. 3. 12 
ScalbX D. 3. 9. 4. D. 3. 12 
Scale Procedure E. 12. 4. 2 
Scale-Factor 1. 4 

syntax 1. 4 
ScalePt Procedure 
Scan Function A 
Scaneq Function 11. 8. 1 
SCanne Function 11. 8. 2 
Scope 2. 2 

of standard objects 2. 2. 5 
Screen 10. 3, 10. 3. 7. 2, F. 3 

contrast F. 3. 1 

cursor control 10. 3. 7. 2, F. 2 
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fading F. 3. 2 

physical 10. 3 
ScreenContrast Data Type F. 10 
ScreenSize Procedure F. 3 
Scroll Rect Procedure E. 9. 13 
Seconds Data Type F. 10 
SectRect Function E. 9. 6 
SectRgn Procedure E. 9. 11 
Seed D. 3. 10. 5 
Seek Procedure 10. 2. 3 
Segment Keyword A 
Segmentation 8. 3, Notes 9-1 
Segments 8. 3, 9. 1, 9. 2. 1 
Selector in Case Statement 6. 2. 2. 2 
Series of payments D. 4. 8 
Set 3. 2. 3, 5. 1. 4, 5. 1. 5. 4, 5. 3 

comparisons 5. 1. 5. 4 

membership testing 5. 1. 5. 5 

operators 5. 1. 4 

values 5. 3 
Set-Constructor 5, 5. 3 

syntsix 5. 3 
Set-Type 3.2.3 

syntax 3. 2. 3 
SetClip Procedure E. 9. 1 
SetContrast Procedure F. 3. 1 
SetCursor Procedure E. 9. 2 
SetDateTime Procedure F. 8 
SetDimContrast Procedure F. 3. 2 
SetEmptyRgn Procedure E. 9. 11 
SetEnv D. 3. 8. 1, D. 3. 8. 2 D. 3. 12 
SetFadeDelay Procedure F. 3. 2 
SetHlt D. 3. 8. 2, D. 3. 12 
SetHlt Address D. 3. 8. 2, D. 3. 11, D. 3. 12 
SetLegends Procedure F. 5. 1 
SetOrigin Procedure E. 9. 1 
SetPenState Procedure E. 9. 3 
SetPort Procedure E. 9. 1 
SetPort3D Procedure E. 12. 4 
SetPortBits Procedure E. 9. 1 
SetPrecision D. 4. 2, D. 4. 12 
SetPt Procedure E. 9. 17 
SetPt2D Procedure E. 12. 4 
SetPt3D Procedure E. 12. 4 
SetRect Procedure E. 9. 6 
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SetRectRgn Procedure E. 9. 11 

SetRnd D. 3. 8. 1, D. 3. 12 

SetRepeatRate Procedure F. 5. 5 

SetStdProcs Procedure E. 10 

SetTimeStamp Procedure F. 9 

SetVolume Procedure F. 4 

SetXcp D. 3. 8. 2, D. 3. 12 

Sgn D. 3. 4. 2, D. 3. 12, D. 4. 7, D. 4. 12 

Shared Intrinsic-Unit Notes 9-1 

ShowCursor Procedure E. 9. 2 

ShowPen Procedure E. 9. 3 

Sig D. 3. 4. 2, D. 3. 12. D. 4. 7. D. 4. 12 

SigDig D. 3. 12 

SIGDIGLEN D. 3. 12 

Sig-FFarm D. 4. 6 

Sig-FForm D. 4. 12 

Sign 1.4 

syntax 1. 4 
Sign D. 3. 7. 1 
SignDfX D. 4. 4 
SignOfX D. 4. 12 
Sign Manipulation D. 3. 9. 2 
Signaling NaN 0.3.7.1 
Signed Zero 3. 1. 1. 3 
Signed-Number 1. 4 

syntax 1. 4 
Silence Procedure F. 4 
Simple-Expression 5 

syntax 5 
Simple-Statement 6. 1 

syntax 6. 1 
Simple-Type 3. 1 

syntax 3. 1 
Simple-Type-Identifier 3 
Sin Function 11. 4. 4 
Sine D. 3. 10. 4 
Single D. 3. 12 

Single, Double, Comp Extended D. 3. 2 
Singular D. 4. 10. 1 
SinhX D. 4. 3, D. 4. 12 
SinX D. 3. 10. 4, D. 3. 12 
Size-Attribute 3. 1. 1. 6 

syntax 3. 1. 1. 6 
Sizeof Function 11. 7. 3 
Skew Procedure E. 12. 4. 2 
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SNAN D. 3. 7. 1, D. 3. 12 

Solving a system of linear equations D. 4. 10. 3 

Sorted D. 4. 5 

Source Transfer Mode E. 7. 1 

SpaceExtra Procedure E. 9. 4 

Speaker F, 4 

SpeakerVolume Data Type F. 10 

Special Symbols 1. 1 

Sqr Function 11. 4. 3 

Sqrt Function 11. 4. 8, D 

SqrtX D. 3. 3. 3, D. 3. 12 

Square Root D. 3. 3. 3 

Stable D. 4. 5 

Stack Space and Memavail Function 

11. 2. 5 
Standard Apple Numeric Environment D-1 
Standard errors D. 4. 10. 7 
Standard Procedures and Functions 

for I/O 10 

10, 11 
Standard Simple-Types 3. 1 
Statement 6 

syntax 6. 1 
Statement-Part 2. 1 

syntax 2. 1 
Statistical Computatins D. 4. 10. 7 
StdArc Procedure E. 10 
StdBits Procedure E. 10 
StdComment Procedure E. 10 
StdGetPic Procedure E. 10 
StdLine Procedure E. 10 
StdOval Procedure E. 10 
StdPoly Procedure E. 10 
StdPutPic Procedure E. 10 
StdRect Procedure E. 10 
StdRgn Procedure E. 10 
StdText Procedure E. 10 
StdTxMeas Function E. 10 
Str2C D. 3. 4. 2, D. 3. 12 
Str2D D. 3. 4. 2, D. 3. 12 
Str2S D. 3. 4. 2. D. 3. 12 
Str2X D. 3. 4. 2, D. 3. 12 
Str2Dec D. 3. 12 

String 1. 6, 3. 1. 1. 6. 4. 3. 1. 5. 1. 5. 3, 
10.3.1.4, 10.3.3.5, 11.6, A 
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character 4. 3. 1 

comparisons 6. 1. 5. 3 

concatenation 11. 6. 3 

constant 1. 6, 3. 1. 1. 6 

constant comparisons 5. 1. 5. 3 

length function 11. 6. 1 

procedures and functions 11. 6 

reference 4. 3. 1 

substring copying 11. 6. 4 

substring deletion 11. 6. 5 

substring insertion 11. 6. 6 

substring search 11. 6. 2 

values in text-oriented I/O 
10.3.1.4, 10.3.3.5 
String-Character 1. 6 

syntax 1, 6 
String-Type 3. 1. 1. 6 

syntax 3. 1. 1. 6 
String-Type-Identifier 3 
StringWidth Function E. 9. 4 
Structured-Statement 6. 2 

syntax 6. 2 
Structured-Type 3. 2 

syntax 3. 2 
Structured-Type-Identifier 3 
Stuf fHex Procedure E. 9. 18 
Systems of linear equations D. 4. 10. 9 
Style D. 3. 4. 2, D. 3. 12 
SubPt Procedure E. 9. 17 
Subrange-Type 3. 1. 3 
syntax 3. 1. 3 
Subtract D. 3. 3. 1 
SubC D. 3. 3. 1, D. 3. 12 
SubD D. 3. 3. 1, D. 3. 12 
SubSx D. 3, 3. 1, D. 3. 12 
SubX D. 3. 3. 1, D.3. 12 
Succ Function 3. 1» 11. 5. 3 
Successor 3. 1 
Swap D. 4. 5 
Syntax Diagrams, Complete Collection 

C 
Syntax Diagrams, Explanation Preface 
System Intrinsic Library 9. 2. 2, 12. 1 
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T 
Tag Constants In New And Dispose 

procedures 11. 2. 1-2 
Tag-Field 3. 2. 2 
Tag-Field-Type 3. 2. 2 

syntax 3. 2. 2 
Tangent D. 3. 10. 4 
TanhX D. 4. 3, D. 4. 12 
TanX D. 3. 10. 4, D. 3. 12 
Term 5 

syntax 5 
TestHlt D. 3. 8. 2, D. 3. 13 
TestXcp D. 3. 8. 2. D. 3. 12 
Testing Set Membership 5. 1. 5. 5 
Text E. 5. 2 

Text Type 3. 2. 4. 10. 1. 2, 10. 3 
Text-Drawing Routines E. 9. 4 
Text-Oriented I/O 10. 3 
TextFace Procedure E. 9. 4 
Textfile 10.1.2, 10.3, Ar 
TextFont Procedure E. 9. 4 
TextMode Procedure E. 9. 4 
Text Size Procedure E. 9. 4 
TextWidth Function E. 9. 4 
Three-Dimensional Graphics. See 
TFP-byte D. 4. 4, D. 4. 12 
TFP-Comp D. 4. 4, D. 4. 12 
TFP-Double D. 4. 4, D. 4. 12 
TFP-Extended D. 4. 4, D. 4. 12 
TFP-integer D. 4. 4, D. 4. 12 
TFP-longint D. 4. 4, D. 4, 12 
TFP-real D. 4. 4. D. 4. 12 

GrafSD 
Time F. 8, F. 9 
Time Stamp F. 9 
Timer Function (Millisecond Timer) 

F. 7 
Timers F. 6, F. 7 
TimeStamp Function F. 9 
TimeToDate Procedure F, 9 
TONEAREST D. 3. 8. 1, D. 3. 12 
TOWARDZERO D. 3. 7. 1, D. 3. 12 



Index-31 



Pascal Reference Manual Index 

Trail-Point D. 4. 6, D. 4. 12 
Transfer Functions 11. 3 
Transfer modes E. 7. 1 
TransForm Procedure E. 12. 4. 2 
Transformation D. 4. 10. 1 
Transformation Matrix E. 12 
Translate Procedure E. 12. 4. 2 
Transpose D. 4. 10. 3 
Treesearch Procedure A 
Trigonometric Functions D. 3. 10. 4 
Trunc D. 2. 4 

Trunc Function 11. 3. 1, A, D 
Turtlegraphics Unit A 
Type 3 

compatibility and identity 3. 4 

syntax 3 
Type -Conversion Notes 3-1 
Type-Declaration 3 

syntax 3 
Type-Declaration-Part 2. 1, 3. 5 

syntax 2. 1 



u 

UCSD Pascal A 

Unary Arithmetic Operators 5. 1. 2 
UNDERFLOW D, 3. 8. 2, D. 3. 12 
Underscore Character 
UnionRect Procedure E. 9. 6 
UnionRgn Procedure E. 9. 11 
Uniqueness D. 4. 10. 3 
Unit 9 

intrinsic 9. 2 

regular 9. 1 
Unit-Heading Syntax Notes 9-2 
Unit, Intrinsic Notes 9-1 
Univtype Notes 7-2 
UNORD D. 3. 6, D. 3. 12 
Unordered D, 3. 6 
Unsigned-Constant 5 

syntax 5 
Unsigned-Integer 1. 4 

syntax 1. 4 
Unsigned-Number 1. 4 

syntax 1. 4 
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Unsigned-Real 1. 4 

syntax 1. 4 
Untyped File 3. 2. 4, 10.1.1-2, 10.4 

I/O 10. 4 
UPWARD D. 3. 8. 1, D. 3. 12 
Uses D. 3. 1, D. 4. 1 
Uses-Clause 8. 1, 9. 1. 1-2, 9. 2, 9. 3 

syntax 8. 1 
Utility Procedures D. 4. 4 



V 

Value Parameter 7. 3. 1 
ValidPrefix D. 3. 12 
Variable 4 

Variable Parameter 7. 3. 2, A 
Variable-Declaration 4. 1 

syntax 4. 1 
Variable-Declaration-Part 2. 1 

syntax 2. 1 
Variable-Identifier 4. 1 

syntax 4. 1 
Variable-Reference 4. 2 

syntax 4. 1 
Variant 3. 2. 2 

records, new procedure 11. 2. 1 

syntax 3. 2. 2 
Variant-Part 3. 2. 2 

syntax 3. 2. 2 
Vectors and Linear Transformations D. 4. 10. 1 
Vector space D. 4. 10. 1 
Vertical Retrace F. 3 
VHSelect Data Type E. 3. 2 
View Angle Procedure E. 12. 4. 1 
Viewing Pyramid E. 12 
Viewport Procedure E. 12. 4. 1 
VisRgn E. 5 
Volume Function F. 4 



r 

Wedges, Graphic Operations E. 9. 10 

While-Statement 6. 2. 3. 2 

optimization 12. 4 

syntax 6. 2. 3. 2 
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With-Statement 6. 2. 4 

syntax 6. 2. 4 
Wordstream Type A 
Write Procedure 10. 3. 3. A 

with real values D 
Write-Protection of File 10.1.5 
Write In Procedure 10. 3. 4, A 



X 






X2C D. 3. 4. 1, 


D.3. 


12 


X2D D. 3. 4. 1, 


D.3. 


12 


X2I D. 3. 4. 1, 


D. 3. 


12 


X2L D. 3. 4. 1, 


D.3. 


12 


X2LDec D. 4. 7. 


D. 4. 


12 


X2S D. 3. 4. 1, 


D.3. 


12 


X2X D. 3. 4. 1. 


D. 3. 


12 


X2Dec D. 3. 4. 2 


, D. 3-12 


X2Str D. 3. 4. 2 


, D. 3. 12 


XForm Matrix 


E. 12 




Xpvrl D. 3. 10. 


2. D. 


3.12 


XpwrY D. 3. 10. 


2, D. 


3.12 


XorRgn Procedure E. 9. 11 


Y 

Yaw Procedure 


E. 12. 4. 2 



ZERO D. 3. 7. 1, D. 3. 12 

Zero D. 2. 1. D. 3. 7. 1 

Zero of a Nonlinear Function D. 4. 9 

Zero of polynonial function D. 4. 9 

Zero Signed 3. 1. 1. 3 



CHARACTERS 

$C Compiler Commands 12. 1 
$0 Compiler Commands 12. 1 
$DECL Compiler Command 12. 2. 1 
$E Compiler Command 12. 1 
$ELSEC Compiler Command 12. 2. 4 
$ENDC Compiler Command 12.2.4 
$1 Compiler Command 12. 1 
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$IFC Compiler Command 12. 2. 4 
$L Compiler Commands 12.1 
$R Compiler Commands 3. 1. 3, 12. 1 
$S Compiler Command 8. 3, 9.1, 9.2, 

12.1 
$SETC Compiler Command 12. 2. 1 
$U Compiler Commands 9. 1. 2, 9. 2. 2, 

12.1 
$X Compiler Commands 12.1 
0, Signed 3. 1. 1. 3 
16-Bit Integer Arithmetic 3. 1. 1. 1-2, 

11.3.3 
32-Bit Integer Arithmetic 3. 1. 1. 2, 

11. 3. 3 
3D Graphics. See Graf 3D. 
@ Operator 3. 3, 5. 1. 6 
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